@spfn/core 0.3.0-beta.1 → 0.3.0-beta.3

package/README.md

@@ -292,8 +292,8 @@ export default defineServerConfig()
 
 All three log the pending list as a warning rather than silently continuing.
 
-**A readiness probe sees the same thing.** When detailed health is on, `GET /health`
-carries a `migrations` object beside `services`:
+**A readiness probe sees the same thing.** When detailed health is on,
+`GET /_core/health` carries a `migrations` object beside `services`:
 
 ```json
 {
@@ -320,6 +320,45 @@ The serverless path (`createServerlessApp`) has no boot to gate — run
 
 ---
 
+## Which path does the health endpoint answer on?
+
+`/_core/health`. That is the whole answer — `@spfn/core` registers nothing on `/health`.
+
+`/_core/` belongs to `@spfn/core` the way `/_auth/` belongs to `@spfn/auth`: the endpoints
+in it are registered before your routes, so no route you declare can take one. That is
+what makes `/_core/health` the right target for a readiness probe, a Dockerfile
+`HEALTHCHECK` or an uptime monitor — the answer does not depend on what your app defines.
+
+```typescript
+// the endpoint answers at /_core/health, and nowhere else
+export default defineServerConfig().build();
+
+// an additional address, for a probe path you cannot change
+export default defineServerConfig().healthCheck({ path: '/health' }).build();
+
+// off → nothing answers anywhere
+export default defineServerConfig().healthCheck({ enabled: false }).build();
+```
+
+`healthCheck.path` adds a second address. It never moves `/_core/health`, and it is
+registered before your routes like the canonical one — so an app route on the same path
+will not run, and the server says so at boot.
+
+**`/health` is yours now.** Declare `GET /health` and it behaves like any other route of
+yours. Declare nothing there and, for one release, a `GET` answers **410** naming
+`/_core/health`, and the server warns once the first time it is hit — a readiness probe
+failure shows an operator neither a response body nor a status text, so a bare 404 would
+leave them nothing to search for. Upgrading an existing deployment?
+[docs/guides/migration/health-endpoint.md](../../docs/guides/migration/health-endpoint.md).
+
+Every built-in health address is registered before the `lifecycle.beforeRoutes` hook, and
+a Hono middleware only wraps handlers registered after it. So a global guard your app adds
+in that hook — which is what the hook is documented for — cannot close the endpoint a
+probe depends on, and a probe reaches it unauthenticated. An app with `src/server/app.ts`
+(level 3) wires its own server and gets no health endpoint at all.
+
+---
+
 ## Can I deploy this to Vercel?
 
 Yes, and it is a first-class target rather than a workaround. From your app:
@@ -369,11 +408,10 @@ path: `spfn build && spfn start`, or the generated Docker files.
 Put the contract in a file and let the agent read it, instead of describing the
 architecture again in every prompt.
 
-An SPFN repository ships an `AGENTS.md` stating what the repo is, the commands, the
+The SPFN repository states it in `CONTRIBUTING.md`: what the repo is, the commands, the
 vertical-slice pattern, and the rules that are not negotiable — never hand-edit generated
-files, migrations come from the schema. Tool-specific files (`CLAUDE.md`,
-`.cursorrules`) point at it in one line rather than duplicating it, so they cannot drift
-apart. Projects created by `spfn create` get the same arrangement.
+files, migrations come from the schema. One file answers to people and agents alike, so
+there is no second copy to drift apart from the first.
 
 Each module README under `src/` is written for the same reader. When an agent is working
 on database code, `src/db/README.md` is the page to give it.
@@ -389,12 +427,11 @@ vertical slice whose path lives under `/_ops/`.
 ```typescript
 // src/server/ops.ts
 import { Type } from '@sinclair/typebox';
-import { route } from '@spfn/core/route';
-import { createOpsRouter } from '@spfn/core/ops';
+import { createOpsRouter, opsRoute } from '@spfn/core/ops';
 import { opsTokenAuth, requireOpsScope } from '@spfn/auth/server';
 
 export const opsRouter = createOpsRouter({
-    listSignups: route.get('/_ops/signups')
+    listSignups: opsRoute.get('/signups')                    // GET /_ops/signups
         .use([requireOpsScope('waitlist:read')])
         .input({ query: Type.Object({ limit: Type.Optional(Type.Number()) }) })
         .handler(async (c) => signupsRepository.list((await c.data()).query.limit)),
@@ -404,16 +441,41 @@ export const opsRouter = createOpsRouter({
 export const appRouter = defineRouter({ ... }).packages([opsRouter]);
 ```
 
-`createOpsRouter` refuses a route outside `/_ops/`, injects the auth middleware into every
-route (there is no unauthenticated variant), and serves `GET /_ops/_manifest` — the
-self-description the CLI reads, with each command's TypeBox schemas as JSON Schema:
+`opsRoute` is `route` with the `/_ops` namespace applied, so a definition carries only the
+path this app owns — what that path looks like, how it nests, which segments are
+parameters are the app's decisions. It exists from `@spfn/core` **0.3.0-beta.2**.
+`createOpsRouter` injects the auth middleware into every route (there is no
+unauthenticated variant) and serves `GET /_ops/_manifest` — the self-description the CLI
+reads, with each command's TypeBox schemas as JSON Schema.
+
+The manifest is registered ahead of the ops routes, so none of them can take its URL even
+when one is a pattern like `/_ops/:name`. That ordering does not reach outside the ops
+router: routes an app declares in its own router are registered before any package router,
+so a pattern there that covers `/_ops/_manifest` — a `/*` catch-all, say — shadows the
+manifest, exactly as it shadows every other package route.
 
 Routes may be grouped in nested `defineRouter`s, and a group's own `.use()` middlewares
-apply to its routes as usual. Three things are refused when the surface is defined, rather
-than discovered in production: two routes sharing a command name (the manifest flattens
-nested groups into one list, so the CLI could not tell them apart), the reserved name
-`getOpsManifest`, and a group mounting `.packages()` (those routes register without the
-prefix check or the auth injection).
+apply to its routes — always after the injected auth, so a group-wide guard reads a
+request that has already been authenticated. A group-level middleware must be a named one;
+wrap a factory to give it a name:
+
+```typescript
+const requireAdmin = defineMiddleware('opsAdminScope', requireOpsScope('admin:read'));
+
+export const opsRouter = createOpsRouter({
+    admin: defineRouter({ getStats, reindex }).use([requireAdmin]),
+}, { auth: opsTokenAuth });
+```
+
+Note that a group's `.use()` middleware carries its `skips` into every route in the group,
+suppressing that server-level middleware there.
+
+Three things are refused when the surface is defined, rather than discovered in
+production: a route built with `route` instead of `opsRoute` (it would carry no
+namespace), two routes sharing a command name (the manifest flattens nested groups into
+one list, so the CLI could not tell them apart), and a group mounting `.packages()` (those
+routes register with neither the namespace nor the auth injection). The command name
+`getOpsManifest` and the path `/_ops/_manifest` are reserved.
 
 ```bash
 spfn ops list --app https://api.example.com          # discover commands
@@ -422,10 +484,11 @@ spfn ops call listSignups --describe                  # print its usage (--json
 ```
 
 Authentication is an ops token from [`@spfn/auth`](../auth/README.md#ops-tokens-spfn-ops):
-scoped, revocable, hash-stored, issued with `spfn ops token issue` where database access
-already exists — a deployed app has no token-creation endpoint. On macOS the CLI keeps the
-token in the keychain (`spfn ops token store`), and resolution order is `--token` →
-`SPFN_OPS_TOKEN` → keychain.
+scoped, revocable, hash-stored, issued with `spfn ops token issue` against the running app
+— the CLI signs in as an administrator, so issuance needs no database access. On macOS the
+CLI keeps the token in the keychain (`spfn ops token store`), and resolution order is
+`--token` → `SPFN_OPS_TOKEN` → keychain. The `--app` URL must be https, since every command
+carries a secret; `http` is accepted only against a loopback host.
 
 ---
 

package/dist/app-config/index.d.ts

@@ -0,0 +1,96 @@
+/**
+ * `spfn.config.js` — the app's serving shape, read by both the CLI and the server.
+ *
+ * The file has existed since `spfn init` started writing it, and until now
+ * nothing read it back. It is the one committed place that describes how an app
+ * is served, which makes it the right home for the ports: an app that wants a
+ * different port says so once here instead of repeating the number across its
+ * `server.config.ts`, Dockerfile, compose file, `next.config.ts` and env
+ * example, where nothing checks that the copies still agree.
+ *
+ * This module is deliberately free of side effects. `@spfn/core/config`
+ * validates the whole environment schema the moment it is imported, which is
+ * fine inside a server and wrong inside a CLI that has not been handed an
+ * app's environment yet.
+ *
+ * @module app-config
+ */
+/**
+ * Ports the app is served on.
+ *
+ * Two names because two processes are started. Next.js reads `PORT` as its own,
+ * so the SPFN server cannot claim that name without the two colliding whenever
+ * they run together.
+ */
+interface SpfnPorts {
+    /** Next.js frontend. Passed to `next` as `-p`. */
+    next?: number;
+    /** SPFN API server. */
+    server?: number;
+}
+interface SpfnAppConfig {
+    ports?: SpfnPorts;
+    /** Host the SPFN API server binds. */
+    host?: string;
+    /** Deployment settings — untouched by this module, kept so the type is whole. */
+    [key: string]: unknown;
+}
+/**
+ * The single place each default exists.
+ *
+ * Defaults live at the bottom of the chain and nowhere else. A default declared
+ * at an input layer — a commander option, a generated entry file, an env schema
+ * — cannot be told apart from a value someone supplied, so it silently outranks
+ * whatever is below it. Three separate defects in this repository came from
+ * exactly that, including an env schema default that forced the environment to
+ * be consulted last and made an injected port unreachable.
+ */
+declare const PORT_DEFAULTS: {
+    readonly next: 3790;
+    readonly server: 8790;
+};
+declare const HOST_DEFAULT = "localhost";
+/**
+ * Read `spfn.config.js` from an app directory.
+ *
+ * Returns an empty object when there is no file, and also when the file cannot
+ * be imported — a malformed deployment config must not stop a server from
+ * booting. The caller decides whether the absence is worth reporting.
+ */
+declare function loadAppConfig(cwd?: string): Promise<SpfnAppConfig>;
+/**
+ * The port each process binds, given a loaded config and the environment.
+ *
+ * Three layers, in this order, and no more: environment variable, then
+ * `spfn.config.js`, then the default.
+ */
+declare function resolvePorts(config: SpfnAppConfig, env?: NodeJS.ProcessEnv): {
+    next: number;
+    server: number;
+};
+/**
+ * The host the SPFN server binds, on the same three layers.
+ *
+ * `localhost` by default: a container states `SPFN_HOST=0.0.0.0` in its own
+ * files, where that decision belongs, rather than every developer machine
+ * publishing a dev server to its network.
+ */
+declare function resolveHost(config: SpfnAppConfig, env?: NodeJS.ProcessEnv): string;
+/**
+ * Where the SPFN server binds, including the address a server config may still
+ * carry through `.port()` / `.host()`.
+ *
+ * Those two are deprecated and sit between `spfn.config.js` and the default for
+ * one release, so an app that has not moved yet keeps the address it had. Once
+ * they are removed this collapses back to {@link resolvePorts} and
+ * {@link resolveHost}.
+ */
+declare function resolveServerAddress(config: SpfnAppConfig, deprecated?: {
+    port?: number;
+    host?: string;
+}, env?: NodeJS.ProcessEnv): {
+    port: number;
+    host: string;
+};
+
+export { HOST_DEFAULT, PORT_DEFAULTS, type SpfnAppConfig, type SpfnPorts, loadAppConfig, resolveHost, resolvePorts, resolveServerAddress };

package/dist/app-config/index.js

@@ -0,0 +1,58 @@
+import { existsSync } from 'fs';
+import { pathToFileURL } from 'url';
+import { join } from 'path';
+
+// src/app-config/index.ts
+var PORT_DEFAULTS = {
+  next: 3790,
+  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 resolvePorts(config, env = process.env) {
+  return {
+    next: readPort(env.NEXT_PORT) ?? config.ports?.next ?? PORT_DEFAULTS.next,
+    server: readPort(env.SPFN_PORT) ?? config.ports?.server ?? PORT_DEFAULTS.server
+  };
+}
+function resolveHost(config, env = process.env) {
+  return env.SPFN_HOST || config.host || HOST_DEFAULT;
+}
+function resolveServerAddress(config, deprecated = {}, env = process.env) {
+  return {
+    port: readPort(env.SPFN_PORT) ?? config.ports?.server ?? deprecated.port ?? PORT_DEFAULTS.server,
+    host: env.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;
+}
+
+export { HOST_DEFAULT, PORT_DEFAULTS, loadAppConfig, resolveHost, resolvePorts, resolveServerAddress };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/app-config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/app-config/index.ts"],"names":[],"mappings":";;;;;AA2DO,IAAM,aAAA,GAAgB;AAAA,EACzB,IAAA,EAAM,IAAA;AAAA,EACN,MAAA,EAAQ;AACZ;AAEO,IAAM,YAAA,GAAe;AAE5B,IAAM,iBAAA,GAAoB;AAAA,EACtB,gBAAA;AAAA,EACA;AACJ,CAAA;AASA,eAAsB,aAAA,CAAc,GAAA,GAAc,OAAA,CAAQ,GAAA,EAAI,EAC9D;AACI,EAAA,KAAA,MAAW,YAAY,iBAAA,EACvB;AACI,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,GAAA,EAAK,QAAQ,CAAA;AAEnC,IAAA,IAAI,CAAC,UAAA,CAAW,QAAQ,CAAA,EACxB;AACI,MAAA;AAAA,IACJ;AAEA,IAAA,IACA;AAGI,MAAA,MAAM,MAAA,GAAS,MAAM,OAAO,aAAA,CAAc,QAAQ,CAAA,CAAE,IAAA,CAAA;AAEpD,MAAA,OAAQ,MAAA,CAAO,WAAW,EAAC;AAAA,IAC/B,SACO,KAAA,EACP;AAQI,MAAA,OAAA,CAAQ,IAAA;AAAA,QACJ,CAAA,cAAA,EAAO,QAAQ,CAAA,2EAAA,EACU,KAAA,YAAiB,QAAQ,KAAA,CAAM,OAAA,GAAU,MAAA,CAAO,KAAK,CAAC,CAAA;AAAA,OACnF;AAEA,MAAA,OAAO,EAAC;AAAA,IACZ;AAAA,EACJ;AAEA,EAAA,OAAO,EAAC;AACZ;AAQO,SAAS,YAAA,CACZ,MAAA,EACA,GAAA,GAAyB,OAAA,CAAQ,GAAA,EAErC;AACI,EAAA,OAAO;AAAA,IACH,IAAA,EAAM,SAAS,GAAA,CAAI,SAAS,KAAK,MAAA,CAAO,KAAA,EAAO,QAAQ,aAAA,CAAc,IAAA;AAAA,IACrE,MAAA,EAAQ,SAAS,GAAA,CAAI,SAAS,KAAK,MAAA,CAAO,KAAA,EAAO,UAAU,aAAA,CAAc;AAAA,GAC7E;AACJ;AASO,SAAS,WAAA,CACZ,MAAA,EACA,GAAA,GAAyB,OAAA,CAAQ,GAAA,EAErC;AACI,EAAA,OAAO,GAAA,CAAI,SAAA,IAAa,MAAA,CAAO,IAAA,IAAQ,YAAA;AAC3C;AAWO,SAAS,qBACZ,MAAA,EACA,UAAA,GAA+C,EAAC,EAChD,GAAA,GAAyB,QAAQ,GAAA,EAErC;AACI,EAAA,OAAO;AAAA,IACH,IAAA,EAAM,QAAA,CAAS,GAAA,CAAI,SAAS,CAAA,IACrB,OAAO,KAAA,EAAO,MAAA,IACd,UAAA,CAAW,IAAA,IACX,aAAA,CAAc,MAAA;AAAA,IACrB,MAAM,GAAA,CAAI,SAAA,IACH,MAAA,CAAO,IAAA,IACP,WAAW,IAAA,IACX;AAAA,GACX;AACJ;AAEA,SAAS,SAAS,KAAA,EAClB;AACI,EAAA,IAAI,CAAC,KAAA,EACL;AACI,IAAA,OAAO,MAAA;AAAA,EACX;AAEA,EAAA,MAAM,IAAA,GAAO,OAAO,KAAK,CAAA;AAEzB,EAAA,OAAO,MAAA,CAAO,UAAU,IAAI,CAAA,IAAK,OAAO,CAAA,IAAK,IAAA,GAAO,QAAQ,IAAA,GAAO,MAAA;AACvE","file":"index.js","sourcesContent":["/**\n * `spfn.config.js` — the app's serving shape, read by both the CLI and the server.\n *\n * The file has existed since `spfn init` started writing it, and until now\n * nothing read it back. It is the one committed place that describes how an app\n * is served, which makes it the right home for the ports: an app that wants a\n * different port says so once here instead of repeating the number across its\n * `server.config.ts`, Dockerfile, compose file, `next.config.ts` and env\n * example, where nothing checks that the copies still agree.\n *\n * This module is deliberately free of side effects. `@spfn/core/config`\n * validates the whole environment schema the moment it is imported, which is\n * fine inside a server and wrong inside a CLI that has not been handed an\n * app's environment yet.\n *\n * @module app-config\n */\n\nimport { existsSync } from 'fs';\nimport { pathToFileURL } from 'url';\nimport { join } from 'path';\n\n/**\n * Ports the app is served on.\n *\n * Two names because two processes are started. Next.js reads `PORT` as its own,\n * so the SPFN server cannot claim that name without the two colliding whenever\n * they run together.\n */\nexport interface SpfnPorts\n{\n    /** Next.js frontend. Passed to `next` as `-p`. */\n    next?: number;\n\n    /** SPFN API server. */\n    server?: number;\n}\n\nexport interface SpfnAppConfig\n{\n    ports?: SpfnPorts;\n\n    /** Host the SPFN API server binds. */\n    host?: string;\n\n    /** Deployment settings — untouched by this module, kept so the type is whole. */\n    [key: string]: unknown;\n}\n\n/**\n * The single place each default exists.\n *\n * Defaults live at the bottom of the chain and nowhere else. A default declared\n * at an input layer — a commander option, a generated entry file, an env schema\n * — cannot be told apart from a value someone supplied, so it silently outranks\n * whatever is below it. Three separate defects in this repository came from\n * exactly that, including an env schema default that forced the environment to\n * be consulted last and made an injected port unreachable.\n */\nexport const PORT_DEFAULTS = {\n    next: 3790,\n    server: 8790,\n} as const;\n\nexport const HOST_DEFAULT = 'localhost';\n\nconst CONFIG_FILE_NAMES = [\n    'spfn.config.js',\n    'spfn.config.mjs',\n] as const;\n\n/**\n * Read `spfn.config.js` from an app directory.\n *\n * Returns an empty object when there is no file, and also when the file cannot\n * be imported — a malformed deployment config must not stop a server from\n * booting. The caller decides whether the absence is worth reporting.\n */\nexport async function loadAppConfig(cwd: string = process.cwd()): Promise<SpfnAppConfig>\n{\n    for (const fileName of CONFIG_FILE_NAMES)\n    {\n        const fullPath = join(cwd, fileName);\n\n        if (!existsSync(fullPath))\n        {\n            continue;\n        }\n\n        try\n        {\n            // A file URL, not a path: on Windows an absolute path is not a\n            // valid ESM specifier, and this file is imported at runtime.\n            const module = await import(pathToFileURL(fullPath).href);\n\n            return (module.default ?? {}) as SpfnAppConfig;\n        }\n        catch (error)\n        {\n            // Falling back to defaults, and saying so. A file that exists and\n            // cannot be imported is a typo, not an absence — silence would send\n            // the server to port 8790 while its own config named another, and\n            // the only symptom would be a port nobody chose.\n            //\n            // console, not the server logger: this runs inside the CLI too,\n            // before any logger is configured.\n            console.warn(\n                `⚠️  ${fileName} could not be imported — falling back to defaults `\n                + `for ports and host. ${error instanceof Error ? error.message : String(error)}`,\n            );\n\n            return {};\n        }\n    }\n\n    return {};\n}\n\n/**\n * The port each process binds, given a loaded config and the environment.\n *\n * Three layers, in this order, and no more: environment variable, then\n * `spfn.config.js`, then the default.\n */\nexport function resolvePorts(\n    config: SpfnAppConfig,\n    env: NodeJS.ProcessEnv = process.env,\n): { next: number; server: number }\n{\n    return {\n        next: readPort(env.NEXT_PORT) ?? config.ports?.next ?? PORT_DEFAULTS.next,\n        server: readPort(env.SPFN_PORT) ?? config.ports?.server ?? PORT_DEFAULTS.server,\n    };\n}\n\n/**\n * The host the SPFN server binds, on the same three layers.\n *\n * `localhost` by default: a container states `SPFN_HOST=0.0.0.0` in its own\n * files, where that decision belongs, rather than every developer machine\n * publishing a dev server to its network.\n */\nexport function resolveHost(\n    config: SpfnAppConfig,\n    env: NodeJS.ProcessEnv = process.env,\n): string\n{\n    return env.SPFN_HOST || config.host || HOST_DEFAULT;\n}\n\n/**\n * Where the SPFN server binds, including the address a server config may still\n * carry through `.port()` / `.host()`.\n *\n * Those two are deprecated and sit between `spfn.config.js` and the default for\n * one release, so an app that has not moved yet keeps the address it had. Once\n * they are removed this collapses back to {@link resolvePorts} and\n * {@link resolveHost}.\n */\nexport function resolveServerAddress(\n    config: SpfnAppConfig,\n    deprecated: { port?: number; host?: string } = {},\n    env: NodeJS.ProcessEnv = process.env,\n): { port: number; host: string }\n{\n    return {\n        port: readPort(env.SPFN_PORT)\n            ?? config.ports?.server\n            ?? deprecated.port\n            ?? PORT_DEFAULTS.server,\n        host: env.SPFN_HOST\n            || config.host\n            || deprecated.host\n            || HOST_DEFAULT,\n    };\n}\n\nfunction readPort(value: string | undefined): number | undefined\n{\n    if (!value)\n    {\n        return undefined;\n    }\n\n    const port = Number(value);\n\n    return Number.isInteger(port) && port > 0 && port < 65536 ? port : undefined;\n}\n"]}

package/dist/config/index.d.ts

@@ -407,27 +407,6 @@ declare const coreEnvSchema: {
     } & {
         key: "DB_MAX_ROWS";
     };
-    PORT: {
-        description: string;
-        default: number;
-        examples: number[];
-    } & {
-        type: "number";
-        validator: (value: string) => number;
-    } & {
-        key: "PORT";
-    };
-    HOST: {
-        description: string;
-        default: string;
-        required: boolean;
-        examples: string[];
-    } & {
-        type: "string";
-        validator: (value: string) => string;
-    } & {
-        key: "HOST";
-    };
     SERVER_TIMEOUT: {
         description: string;
         default: number;
@@ -1017,27 +996,6 @@ declare const registry: _spfn_core_env.EnvRegistry<{
     } & {
         key: "DB_MAX_ROWS";
     };
-    PORT: {
-        description: string;
-        default: number;
-        examples: number[];
-    } & {
-        type: "number";
-        validator: (value: string) => number;
-    } & {
-        key: "PORT";
-    };
-    HOST: {
-        description: string;
-        default: string;
-        required: boolean;
-        examples: string[];
-    } & {
-        type: "string";
-        validator: (value: string) => string;
-    } & {
-        key: "HOST";
-    };
     SERVER_TIMEOUT: {
         description: string;
         default: number;
@@ -1620,27 +1578,6 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "DB_MAX_ROWS";
     };
-    PORT: {
-        description: string;
-        default: number;
-        examples: number[];
-    } & {
-        type: "number";
-        validator: (value: string) => number;
-    } & {
-        key: "PORT";
-    };
-    HOST: {
-        description: string;
-        default: string;
-        required: boolean;
-        examples: string[];
-    } & {
-        type: "string";
-        validator: (value: string) => string;
-    } & {
-        key: "HOST";
-    };
     SERVER_TIMEOUT: {
         description: string;
         default: number;

package/dist/config/index.js

@@ -251,17 +251,17 @@ var coreEnvSchema = defineEnvSchema({
   // ========================================================================
   // Server - Core
   // ========================================================================
-  PORT: envNumber({
-    description: "Server port number",
-    default: 4e3,
-    examples: [3e3, 4e3, 8080]
-  }),
-  HOST: envString({
-    description: "Server hostname",
-    default: "localhost",
-    required: false,
-    examples: ["localhost", "0.0.0.0", "127.0.0.1"]
-  }),
+  // PORT and HOST are deliberately absent.
+  //
+  // They were declared here with defaults of 4000 and 'localhost', and a
+  // schema default is indistinguishable from a value someone set — so
+  // `env.PORT` was never undefined, and the resolution order had to consult
+  // the environment last to avoid it winning every time. That is what made an
+  // injected port unreachable. The server's address now resolves through
+  // `@spfn/core/app-config`: SPFN_PORT, then spfn.config.js, then the
+  // default, with the default existing in exactly one place.
+  //
+  // `PORT` is also Next.js's own variable, and two processes are started.
   // ========================================================================
   // Server - Timeout
   // ========================================================================

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/config/schema.ts","../../src/config/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Core Package Environment Variable Schema\n *\n * Centralized schema definition for all environment variables used in @spfn/core.\n * This provides type safety, validation, and documentation for environment configuration.\n *\n * @module config/schema\n */\n\nimport {\n    defineEnvSchema,\n    envEnum,\n    envNumber,\n    envBoolean,\n    envUrl,\n    envString,\n    parsePostgresUrl,\n    parseRedisUrl,\n} from '@spfn/core/env';\n\n/**\n * Core package environment variable schema\n *\n * Defines all environment variables with:\n * - Type information\n * - Default values\n * - Validation rules\n * - Documentation\n *\n * @example\n * ```typescript\n * import { coreEnvSchema } from '@spfn/core/config';\n *\n * // Access schema information\n * console.log(coreEnvSchema.DB_POOL_MAX.description);\n * console.log(coreEnvSchema.DB_POOL_MAX.default);\n * ```\n */\nexport const coreEnvSchema = defineEnvSchema({\n    // ========================================================================\n    // Core Environment\n    // ========================================================================\n\n    NODE_ENV: envEnum(['local', 'development', 'staging', 'production', 'test'] as const, {\n        description: 'Node.js runtime environment',\n        default: 'local',\n        nextjs: true,\n    }),\n\n    // ========================================================================\n    // Database - Connection\n    // ========================================================================\n\n    DATABASE_URL: envString({\n        description: 'Primary database connection URL',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@localhost:5432/dbname'],\n    }),\n\n    DATABASE_WRITE_URL: envString({\n        description: 'Write database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@master:5432/dbname'],\n    }),\n\n    DATABASE_READ_URL: envString({\n        description: 'Read database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@replica:5432/dbname'],\n    }),\n\n    // ========================================================================\n    // Database - Connection Pool\n    // ========================================================================\n\n    DB_POOL_MAX: envNumber({\n        description: 'Maximum number of database connections in pool',\n        default: 10,\n        examples: [10, 20, 50],\n    }),\n\n    DB_POOL_READ_MAX: envNumber({\n        description: 'Maximum connections for the read-replica pool. Defaults to DB_POOL_MAX. Set lower so write.max + read.max stays under the server max_connections (each process otherwise opens up to 2 × DB_POOL_MAX when a replica is configured).',\n        required: false,\n        examples: [5, 10, 20],\n    }),\n\n    DB_POOL_IDLE_TIMEOUT: envNumber({\n        description: 'Database connection idle timeout in seconds',\n        default: 30,\n        examples: [20, 30, 60],\n    }),\n\n    // ========================================================================\n    // Database - Retry Configuration\n    // ========================================================================\n\n    DB_RETRY_MAX: envNumber({\n        description: 'Maximum number of database connection retry attempts',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_RETRY_INITIAL_DELAY: envNumber({\n        description: 'Initial delay between database retry attempts (milliseconds)',\n        default: 100,\n        examples: [50, 100, 200],\n    }),\n\n    DB_RETRY_MAX_DELAY: envNumber({\n        description: 'Maximum delay cap for database retry attempts (milliseconds)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    DB_RETRY_FACTOR: envNumber({\n        description: 'Exponential backoff factor for database retry delays',\n        default: 2,\n        examples: [2, 1.5, 3],\n    }),\n\n    // ========================================================================\n    // Database - Health Check\n    // ========================================================================\n\n    DB_HEALTH_CHECK_ENABLED: envBoolean({\n        description: 'Enable periodic database health checks',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_INTERVAL: envNumber({\n        description: 'Database health check interval (milliseconds)',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    DB_HEALTH_CHECK_RECONNECT: envBoolean({\n        description: 'Reconnect to database on health check failure',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_MAX_RETRIES: envNumber({\n        description: 'Maximum health check retry attempts before marking as failed',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_HEALTH_CHECK_RETRY_INTERVAL: envNumber({\n        description: 'Interval between health check retry attempts (milliseconds)',\n        default: 5000,\n        examples: [5000, 10000, 15000],\n    }),\n\n    // ========================================================================\n    // Database - Monitoring\n    // ========================================================================\n\n    DB_MONITORING_ENABLED: envBoolean({\n        description: 'Enable database query performance monitoring',\n        default: false,\n        examples: [true, false],\n    }),\n\n    DB_MONITORING_SLOW_THRESHOLD: envNumber({\n        description: 'Slow query threshold for monitoring (milliseconds)',\n        default: 1000,\n        examples: [500, 1000, 2000],\n    }),\n\n    DB_MONITORING_LOG_QUERIES: envBoolean({\n        description: 'Log all database queries (not just slow queries)',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Transaction\n    // ========================================================================\n\n    TRANSACTION_TIMEOUT: envNumber({\n        description: 'Transaction timeout in milliseconds',\n        default: 30000,\n        examples: [10000, 30000, 60000],\n    }),\n\n    TRANSACTION_IDLE_TIMEOUT: envNumber({\n        description: 'Max time (ms) a transaction may sit idle (no running query) before Postgres terminates it and reclaims the pooled connection. Guards against external I/O held inside a transaction starving the connection pool. 0 disables.',\n        default: 30000,\n        examples: [10000, 30000, 0],\n    }),\n\n    // ========================================================================\n    // Jobs (pg-boss)\n    // ========================================================================\n\n    JOB_POLLING_INTERVAL_SECONDS: envNumber({\n        description: 'How often each pg-boss worker polls the DB for new jobs (seconds). Lower = faster pickup, more idle SELECT load; higher = less DB chatter, slower pickup. Per-job override via job options.',\n        default: 2,\n        examples: [1, 2, 10],\n    }),\n\n    // ========================================================================\n    // Database - Development\n    // ========================================================================\n\n    DB_DEBUG_TRACE: envBoolean({\n        description: 'Enable detailed debug tracing for database operations',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Migrations\n    // ========================================================================\n\n    SPFN_ALLOW_PENDING_MIGRATIONS: envBoolean({\n        description: 'Start the server even when a function package or the project has migrations the database has not applied. Off by default: a server booted with pending migrations fails only at request time, as an opaque 500. The flag equivalent is `spfn dev --allow-pending-migrations`.',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Drizzle ORM\n    // ========================================================================\n\n    DRIZZLE_SCHEMA_PATH: envString({\n        description: 'Path to Drizzle schema configuration',\n        required: false,\n        default: './src/server/entities/config.ts',\n        examples: ['./src/db/schema.ts', './src/server/entities/config.ts'],\n    }),\n\n    DRIZZLE_OUT_DIR: envString({\n        description: 'Output directory for Drizzle migrations',\n        required: false,\n        default: './drizzle',\n        examples: ['./drizzle', './migrations'],\n    }),\n\n    // ========================================================================\n    // Logger - Core\n    // ========================================================================\n\n    SPFN_LOG_LEVEL: envEnum(['debug', 'info', 'warn', 'error', 'fatal'] as const, {\n        description: 'Minimum log level to output',\n        default: 'info',\n    }),\n\n    // ========================================================================\n    // Cache (Redis/Valkey)\n    // ========================================================================\n\n    CACHE_URL: envString({\n        description: 'Single Redis/Valkey instance URL',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://localhost:6379', 'rediss://secure.cache.com:6380'],\n    }),\n\n    CACHE_WRITE_URL: envString({\n        description: 'Master Redis/Valkey URL for writes (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://master:6379'],\n    }),\n\n    CACHE_READ_URL: envString({\n        description: 'Replica Redis/Valkey URL for reads (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://replica:6379'],\n    }),\n\n    CACHE_SENTINEL_HOSTS: envString({\n        description: 'Comma-separated Redis Sentinel hosts',\n        required: false,\n        examples: ['sentinel1:26379,sentinel2:26379'],\n    }),\n\n    CACHE_CLUSTER_NODES: envString({\n        description: 'Comma-separated Redis Cluster nodes',\n        required: false,\n        examples: ['node1:6379,node2:6379,node3:6379'],\n    }),\n\n    CACHE_MASTER_NAME: envString({\n        description: 'Redis Sentinel master name',\n        required: false,\n        examples: ['mymaster'],\n    }),\n\n    CACHE_PASSWORD: envString({\n        description: 'Redis/Valkey authentication password',\n        required: false,\n        sensitive: true,\n        examples: ['your-redis-password'],\n    }),\n\n    CACHE_TLS_REJECT_UNAUTHORIZED: envBoolean({\n        description: 'Verify TLS certificates for secure Redis connections',\n        default: true,\n        examples: [true, false],\n    }),\n\n    CACHE_MAX_RETRIES_PER_REQUEST: envNumber({\n        description: 'Max ioredis retries per command before it rejects (fail fast instead of hanging on a cache outage). ioredis default is 20.',\n        default: 3,\n        examples: [1, 3, 20],\n    }),\n\n    CACHE_ENABLE_OFFLINE_QUEUE: envBoolean({\n        description: 'Queue commands while the cache is disconnected (true) vs reject immediately for strict fail-fast (false). Default true keeps resilience to brief blips.',\n        default: true,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Query limits\n    // ========================================================================\n\n    DB_MAX_ROWS: envNumber({\n        description: 'Safety ceiling for rows returned by repository findMany (0 = unlimited). When >0, an unbounded query is capped and an explicit limit is clamped, guarding against accidentally loading a whole large table.',\n        default: 0,\n        examples: [0, 1000, 10000],\n    }),\n\n    // ========================================================================\n    // Server - Core\n    // ========================================================================\n\n    PORT: envNumber({\n        description: 'Server port number',\n        default: 4000,\n        examples: [3000, 4000, 8080],\n    }),\n\n    HOST: envString({\n        description: 'Server hostname',\n        default: 'localhost',\n        required: false,\n        examples: ['localhost', '0.0.0.0', '127.0.0.1'],\n    }),\n\n    // ========================================================================\n    // Server - Timeout\n    // ========================================================================\n\n    SERVER_TIMEOUT: envNumber({\n        description: 'Request timeout in milliseconds',\n        default: 120000,\n        examples: [60000, 120000, 300000],\n    }),\n\n    SERVER_KEEPALIVE_TIMEOUT: envNumber({\n        description: 'Keep-alive timeout in milliseconds',\n        default: 65000,\n        examples: [30000, 65000, 120000],\n    }),\n\n    SERVER_HEADERS_TIMEOUT: envNumber({\n        description: 'Headers timeout in milliseconds',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    SHUTDOWN_TIMEOUT: envNumber({\n        description: 'Graceful shutdown timeout in milliseconds (must be less than k8s terminationGracePeriodSeconds minus preStop sleep, with safety margin)',\n        default: 280000,\n        examples: [30000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Fetch (Node.js undici) - outbound HTTP request timeout\n    // ========================================================================\n\n    FETCH_CONNECT_TIMEOUT: envNumber({\n        description: 'Fetch TCP connection timeout in milliseconds (time to establish socket connection to upstream server)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    FETCH_HEADERS_TIMEOUT: envNumber({\n        description: 'Fetch headers timeout in milliseconds (time to receive response headers after request sent)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    FETCH_BODY_TIMEOUT: envNumber({\n        description: 'Fetch body timeout in milliseconds (time between body data chunks from upstream server)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    // ========================================================================\n    // Next.js Integration\n    // ========================================================================\n\n    SPFN_API_URL: envUrl({\n        description: 'SPFN API URL (used by Next.js to call backend)',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    NEXT_PUBLIC_SPFN_API_URL: envUrl({\n        description: 'SPFN API URL (used by Next.js to call backend)',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    SPFN_APP_URL: envUrl({\n        description: 'Next.js application URL (used by SPFN server)',\n        required: false,\n        nextjs: true,\n        examples: ['http://localhost:3790', 'https://your-app.com'],\n    }),\n\n    RPC_PROXY_TIMEOUT: envNumber({\n        description: 'RPC proxy request timeout in milliseconds (AbortController timeout for proxied requests to backend, should be shorter than FETCH_HEADERS_TIMEOUT)',\n        default: 120000,\n        nextjs: true,\n        examples: [60000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Proxy → Backend trust (HMAC signing)\n    // ========================================================================\n\n    SPFN_PROXY_SECRET: envString({\n        description: 'Shared secret for signing proxy→backend requests (HMAC-SHA256). Read by BOTH processes — the Next.js proxy (to sign) and the SPFN backend (to verify) — so it belongs in .env.local (loaded by both; the backend reads it via loadEnv, Next.js reads it server-side without exposing it to the browser). Set the SAME value on both. Leave unset to disable proxy-guard signing.',\n        required: false,\n        sensitive: true,\n        nextjs: true,\n        examples: ['<32+ byte random hex>', 'v2:<32+ byte random hex>'],\n    }),\n\n    SPFN_PROXY_SECRET_PREVIOUS: envString({\n        description: 'Previous (grace) proxy keys still accepted for verification during rotation — comma-separated <keyId>:<secret>. The proxy never signs with these; they only keep requests signed with the prior key verifying until a rollout settles. Backend-only (verification), so it belongs in .env.server, NOT exposed to the Next.js process.',\n        required: false,\n        sensitive: true,\n        nextjs: false,\n        examples: ['v1:<old secret>', 'v1:<old>,v0:<older>'],\n    }),\n\n    TRUSTED_PROXY_HOPS: envNumber({\n        description: 'Number of trusted reverse proxies in front of the Next.js proxy (e.g. cloud LB + nginx = 2). Read by the proxy to extract the real client IP from the inbound X-Forwarded-For (counting from the right, which your own infra appends and a client cannot spoof) and forward it to the backend for rate limiting. Set it to your actual hop count; too low trusts a client-spoofable entry, too high collapses users behind a shared proxy IP.',\n        default: 1,\n        nextjs: true,\n        examples: [1, 2, 3],\n    }),\n\n    // ========================================================================\n    // Rate limiting (global default limiter)\n    // ========================================================================\n\n    RATE_LIMIT_MODE: envEnum(['off', 'on'] as const, {\n        description: 'Global default rate limiter. \"off\": only routes tagged with rateLimitPolicy() are limited. \"on\": every named-middleware route gets the default limit too (opt out per route with .skip([\\'rateLimit\\'])). Health/SSE/WebSocket endpoints are always exempt. Overridden by defineServerConfig().rateLimit({ mode }).',\n        default: 'off',\n    }),\n\n    RATE_LIMIT_DEFAULT_LIMIT: envNumber({\n        description: 'Max requests per window for the global default limiter (RATE_LIMIT_MODE=on), counted per route and per client IP.',\n        default: 100,\n        examples: [60, 100, 300],\n    }),\n\n    RATE_LIMIT_DEFAULT_WINDOW_MS: envNumber({\n        description: 'Window length in milliseconds for the global default limiter.',\n        default: 60000,\n        examples: [1000, 60000],\n    }),\n\n    RATE_LIMIT_FAIL_CLOSED: envBoolean({\n        description: 'When the cache (Redis/Valkey) backing the limiter is unavailable, reject with 429 instead of counting in-process. Default false: the limiter falls back to per-process counters, so limits still apply — but the effective limit multiplies by the instance count, since each process counts alone. Set true only where a shared count is required and refusing traffic is preferable to a looser one.',\n        default: false,\n    }),\n\n    // ========================================================================\n    // Outbound request safety (SSRF)\n    // ========================================================================\n\n    SAFE_FETCH_BLOCK_PRIVATE_IPS: envBoolean({\n        description: 'Default for safeFetch (@spfn/core/security): block outbound requests that resolve to private/reserved IP ranges, including the cloud metadata address. Keep true in production; set false only for trusted internal-network calls in development. Overridden by defineServerConfig().outboundFetch({ blockPrivateIps }).',\n        default: true,\n    }),\n});\n","/**\n * Core Package Configuration\n *\n * @example\n * ```typescript\n * import { registry } from '@spfn/core/config';\n *\n * const env = registry.validate();\n * console.log(env.DB_POOL_MAX);\n * ```\n *\n * @module config\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { coreEnvSchema } from './schema';\n\n/**\n * Core environment schema\n */\nexport { coreEnvSchema as envSchema } from './schema';\n\n/**\n * Environment registry\n *\n * @example\n * ```typescript\n * // Reset for testing\n * registry.reset();\n * ```\n */\nexport const registry = createEnvRegistry(coreEnvSchema);\n\n/**\n * Validated environment configuration\n */\nexport const env = registry.validate();\n"]}
+{"version":3,"sources":["../../src/config/schema.ts","../../src/config/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Core Package Environment Variable Schema\n *\n * Centralized schema definition for all environment variables used in @spfn/core.\n * This provides type safety, validation, and documentation for environment configuration.\n *\n * @module config/schema\n */\n\nimport {\n    defineEnvSchema,\n    envEnum,\n    envNumber,\n    envBoolean,\n    envUrl,\n    envString,\n    parsePostgresUrl,\n    parseRedisUrl,\n} from '@spfn/core/env';\n\n/**\n * Core package environment variable schema\n *\n * Defines all environment variables with:\n * - Type information\n * - Default values\n * - Validation rules\n * - Documentation\n *\n * @example\n * ```typescript\n * import { coreEnvSchema } from '@spfn/core/config';\n *\n * // Access schema information\n * console.log(coreEnvSchema.DB_POOL_MAX.description);\n * console.log(coreEnvSchema.DB_POOL_MAX.default);\n * ```\n */\nexport const coreEnvSchema = defineEnvSchema({\n    // ========================================================================\n    // Core Environment\n    // ========================================================================\n\n    NODE_ENV: envEnum(['local', 'development', 'staging', 'production', 'test'] as const, {\n        description: 'Node.js runtime environment',\n        default: 'local',\n        nextjs: true,\n    }),\n\n    // ========================================================================\n    // Database - Connection\n    // ========================================================================\n\n    DATABASE_URL: envString({\n        description: 'Primary database connection URL',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@localhost:5432/dbname'],\n    }),\n\n    DATABASE_WRITE_URL: envString({\n        description: 'Write database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@master:5432/dbname'],\n    }),\n\n    DATABASE_READ_URL: envString({\n        description: 'Read database URL (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parsePostgresUrl,\n        examples: ['postgresql://user:password@replica:5432/dbname'],\n    }),\n\n    // ========================================================================\n    // Database - Connection Pool\n    // ========================================================================\n\n    DB_POOL_MAX: envNumber({\n        description: 'Maximum number of database connections in pool',\n        default: 10,\n        examples: [10, 20, 50],\n    }),\n\n    DB_POOL_READ_MAX: envNumber({\n        description: 'Maximum connections for the read-replica pool. Defaults to DB_POOL_MAX. Set lower so write.max + read.max stays under the server max_connections (each process otherwise opens up to 2 × DB_POOL_MAX when a replica is configured).',\n        required: false,\n        examples: [5, 10, 20],\n    }),\n\n    DB_POOL_IDLE_TIMEOUT: envNumber({\n        description: 'Database connection idle timeout in seconds',\n        default: 30,\n        examples: [20, 30, 60],\n    }),\n\n    // ========================================================================\n    // Database - Retry Configuration\n    // ========================================================================\n\n    DB_RETRY_MAX: envNumber({\n        description: 'Maximum number of database connection retry attempts',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_RETRY_INITIAL_DELAY: envNumber({\n        description: 'Initial delay between database retry attempts (milliseconds)',\n        default: 100,\n        examples: [50, 100, 200],\n    }),\n\n    DB_RETRY_MAX_DELAY: envNumber({\n        description: 'Maximum delay cap for database retry attempts (milliseconds)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    DB_RETRY_FACTOR: envNumber({\n        description: 'Exponential backoff factor for database retry delays',\n        default: 2,\n        examples: [2, 1.5, 3],\n    }),\n\n    // ========================================================================\n    // Database - Health Check\n    // ========================================================================\n\n    DB_HEALTH_CHECK_ENABLED: envBoolean({\n        description: 'Enable periodic database health checks',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_INTERVAL: envNumber({\n        description: 'Database health check interval (milliseconds)',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    DB_HEALTH_CHECK_RECONNECT: envBoolean({\n        description: 'Reconnect to database on health check failure',\n        default: true,\n        examples: [true, false],\n    }),\n\n    DB_HEALTH_CHECK_MAX_RETRIES: envNumber({\n        description: 'Maximum health check retry attempts before marking as failed',\n        default: 3,\n        examples: [3, 5, 10],\n    }),\n\n    DB_HEALTH_CHECK_RETRY_INTERVAL: envNumber({\n        description: 'Interval between health check retry attempts (milliseconds)',\n        default: 5000,\n        examples: [5000, 10000, 15000],\n    }),\n\n    // ========================================================================\n    // Database - Monitoring\n    // ========================================================================\n\n    DB_MONITORING_ENABLED: envBoolean({\n        description: 'Enable database query performance monitoring',\n        default: false,\n        examples: [true, false],\n    }),\n\n    DB_MONITORING_SLOW_THRESHOLD: envNumber({\n        description: 'Slow query threshold for monitoring (milliseconds)',\n        default: 1000,\n        examples: [500, 1000, 2000],\n    }),\n\n    DB_MONITORING_LOG_QUERIES: envBoolean({\n        description: 'Log all database queries (not just slow queries)',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Transaction\n    // ========================================================================\n\n    TRANSACTION_TIMEOUT: envNumber({\n        description: 'Transaction timeout in milliseconds',\n        default: 30000,\n        examples: [10000, 30000, 60000],\n    }),\n\n    TRANSACTION_IDLE_TIMEOUT: envNumber({\n        description: 'Max time (ms) a transaction may sit idle (no running query) before Postgres terminates it and reclaims the pooled connection. Guards against external I/O held inside a transaction starving the connection pool. 0 disables.',\n        default: 30000,\n        examples: [10000, 30000, 0],\n    }),\n\n    // ========================================================================\n    // Jobs (pg-boss)\n    // ========================================================================\n\n    JOB_POLLING_INTERVAL_SECONDS: envNumber({\n        description: 'How often each pg-boss worker polls the DB for new jobs (seconds). Lower = faster pickup, more idle SELECT load; higher = less DB chatter, slower pickup. Per-job override via job options.',\n        default: 2,\n        examples: [1, 2, 10],\n    }),\n\n    // ========================================================================\n    // Database - Development\n    // ========================================================================\n\n    DB_DEBUG_TRACE: envBoolean({\n        description: 'Enable detailed debug tracing for database operations',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Migrations\n    // ========================================================================\n\n    SPFN_ALLOW_PENDING_MIGRATIONS: envBoolean({\n        description: 'Start the server even when a function package or the project has migrations the database has not applied. Off by default: a server booted with pending migrations fails only at request time, as an opaque 500. The flag equivalent is `spfn dev --allow-pending-migrations`.',\n        default: false,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Drizzle ORM\n    // ========================================================================\n\n    DRIZZLE_SCHEMA_PATH: envString({\n        description: 'Path to Drizzle schema configuration',\n        required: false,\n        default: './src/server/entities/config.ts',\n        examples: ['./src/db/schema.ts', './src/server/entities/config.ts'],\n    }),\n\n    DRIZZLE_OUT_DIR: envString({\n        description: 'Output directory for Drizzle migrations',\n        required: false,\n        default: './drizzle',\n        examples: ['./drizzle', './migrations'],\n    }),\n\n    // ========================================================================\n    // Logger - Core\n    // ========================================================================\n\n    SPFN_LOG_LEVEL: envEnum(['debug', 'info', 'warn', 'error', 'fatal'] as const, {\n        description: 'Minimum log level to output',\n        default: 'info',\n    }),\n\n    // ========================================================================\n    // Cache (Redis/Valkey)\n    // ========================================================================\n\n    CACHE_URL: envString({\n        description: 'Single Redis/Valkey instance URL',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://localhost:6379', 'rediss://secure.cache.com:6380'],\n    }),\n\n    CACHE_WRITE_URL: envString({\n        description: 'Master Redis/Valkey URL for writes (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://master:6379'],\n    }),\n\n    CACHE_READ_URL: envString({\n        description: 'Replica Redis/Valkey URL for reads (master-replica pattern)',\n        required: false,\n        sensitive: true,\n        validator: parseRedisUrl,\n        examples: ['redis://replica:6379'],\n    }),\n\n    CACHE_SENTINEL_HOSTS: envString({\n        description: 'Comma-separated Redis Sentinel hosts',\n        required: false,\n        examples: ['sentinel1:26379,sentinel2:26379'],\n    }),\n\n    CACHE_CLUSTER_NODES: envString({\n        description: 'Comma-separated Redis Cluster nodes',\n        required: false,\n        examples: ['node1:6379,node2:6379,node3:6379'],\n    }),\n\n    CACHE_MASTER_NAME: envString({\n        description: 'Redis Sentinel master name',\n        required: false,\n        examples: ['mymaster'],\n    }),\n\n    CACHE_PASSWORD: envString({\n        description: 'Redis/Valkey authentication password',\n        required: false,\n        sensitive: true,\n        examples: ['your-redis-password'],\n    }),\n\n    CACHE_TLS_REJECT_UNAUTHORIZED: envBoolean({\n        description: 'Verify TLS certificates for secure Redis connections',\n        default: true,\n        examples: [true, false],\n    }),\n\n    CACHE_MAX_RETRIES_PER_REQUEST: envNumber({\n        description: 'Max ioredis retries per command before it rejects (fail fast instead of hanging on a cache outage). ioredis default is 20.',\n        default: 3,\n        examples: [1, 3, 20],\n    }),\n\n    CACHE_ENABLE_OFFLINE_QUEUE: envBoolean({\n        description: 'Queue commands while the cache is disconnected (true) vs reject immediately for strict fail-fast (false). Default true keeps resilience to brief blips.',\n        default: true,\n        examples: [true, false],\n    }),\n\n    // ========================================================================\n    // Database - Query limits\n    // ========================================================================\n\n    DB_MAX_ROWS: envNumber({\n        description: 'Safety ceiling for rows returned by repository findMany (0 = unlimited). When >0, an unbounded query is capped and an explicit limit is clamped, guarding against accidentally loading a whole large table.',\n        default: 0,\n        examples: [0, 1000, 10000],\n    }),\n\n    // ========================================================================\n    // Server - Core\n    // ========================================================================\n\n    // PORT and HOST are deliberately absent.\n    //\n    // They were declared here with defaults of 4000 and 'localhost', and a\n    // schema default is indistinguishable from a value someone set — so\n    // `env.PORT` was never undefined, and the resolution order had to consult\n    // the environment last to avoid it winning every time. That is what made an\n    // injected port unreachable. The server's address now resolves through\n    // `@spfn/core/app-config`: SPFN_PORT, then spfn.config.js, then the\n    // default, with the default existing in exactly one place.\n    //\n    // `PORT` is also Next.js's own variable, and two processes are started.\n\n    // ========================================================================\n    // Server - Timeout\n    // ========================================================================\n\n    SERVER_TIMEOUT: envNumber({\n        description: 'Request timeout in milliseconds',\n        default: 120000,\n        examples: [60000, 120000, 300000],\n    }),\n\n    SERVER_KEEPALIVE_TIMEOUT: envNumber({\n        description: 'Keep-alive timeout in milliseconds',\n        default: 65000,\n        examples: [30000, 65000, 120000],\n    }),\n\n    SERVER_HEADERS_TIMEOUT: envNumber({\n        description: 'Headers timeout in milliseconds',\n        default: 60000,\n        examples: [30000, 60000, 120000],\n    }),\n\n    SHUTDOWN_TIMEOUT: envNumber({\n        description: 'Graceful shutdown timeout in milliseconds (must be less than k8s terminationGracePeriodSeconds minus preStop sleep, with safety margin)',\n        default: 280000,\n        examples: [30000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Fetch (Node.js undici) - outbound HTTP request timeout\n    // ========================================================================\n\n    FETCH_CONNECT_TIMEOUT: envNumber({\n        description: 'Fetch TCP connection timeout in milliseconds (time to establish socket connection to upstream server)',\n        default: 10000,\n        examples: [5000, 10000, 30000],\n    }),\n\n    FETCH_HEADERS_TIMEOUT: envNumber({\n        description: 'Fetch headers timeout in milliseconds (time to receive response headers after request sent)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    FETCH_BODY_TIMEOUT: envNumber({\n        description: 'Fetch body timeout in milliseconds (time between body data chunks from upstream server)',\n        default: 300000,\n        examples: [120000, 300000, 600000],\n    }),\n\n    // ========================================================================\n    // Next.js Integration\n    // ========================================================================\n\n    SPFN_API_URL: envUrl({\n        description: 'SPFN API URL (used by Next.js to call backend)',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    NEXT_PUBLIC_SPFN_API_URL: envUrl({\n        description: 'SPFN API URL (used by Next.js to call backend)',\n        required: true,\n        nextjs: true,\n        examples: ['http://localhost:8790', 'https://api.your-app.com'],\n    }),\n\n    SPFN_APP_URL: envUrl({\n        description: 'Next.js application URL (used by SPFN server)',\n        required: false,\n        nextjs: true,\n        examples: ['http://localhost:3790', 'https://your-app.com'],\n    }),\n\n    RPC_PROXY_TIMEOUT: envNumber({\n        description: 'RPC proxy request timeout in milliseconds (AbortController timeout for proxied requests to backend, should be shorter than FETCH_HEADERS_TIMEOUT)',\n        default: 120000,\n        nextjs: true,\n        examples: [60000, 120000, 280000],\n    }),\n\n    // ========================================================================\n    // Proxy → Backend trust (HMAC signing)\n    // ========================================================================\n\n    SPFN_PROXY_SECRET: envString({\n        description: 'Shared secret for signing proxy→backend requests (HMAC-SHA256). Read by BOTH processes — the Next.js proxy (to sign) and the SPFN backend (to verify) — so it belongs in .env.local (loaded by both; the backend reads it via loadEnv, Next.js reads it server-side without exposing it to the browser). Set the SAME value on both. Leave unset to disable proxy-guard signing.',\n        required: false,\n        sensitive: true,\n        nextjs: true,\n        examples: ['<32+ byte random hex>', 'v2:<32+ byte random hex>'],\n    }),\n\n    SPFN_PROXY_SECRET_PREVIOUS: envString({\n        description: 'Previous (grace) proxy keys still accepted for verification during rotation — comma-separated <keyId>:<secret>. The proxy never signs with these; they only keep requests signed with the prior key verifying until a rollout settles. Backend-only (verification), so it belongs in .env.server, NOT exposed to the Next.js process.',\n        required: false,\n        sensitive: true,\n        nextjs: false,\n        examples: ['v1:<old secret>', 'v1:<old>,v0:<older>'],\n    }),\n\n    TRUSTED_PROXY_HOPS: envNumber({\n        description: 'Number of trusted reverse proxies in front of the Next.js proxy (e.g. cloud LB + nginx = 2). Read by the proxy to extract the real client IP from the inbound X-Forwarded-For (counting from the right, which your own infra appends and a client cannot spoof) and forward it to the backend for rate limiting. Set it to your actual hop count; too low trusts a client-spoofable entry, too high collapses users behind a shared proxy IP.',\n        default: 1,\n        nextjs: true,\n        examples: [1, 2, 3],\n    }),\n\n    // ========================================================================\n    // Rate limiting (global default limiter)\n    // ========================================================================\n\n    RATE_LIMIT_MODE: envEnum(['off', 'on'] as const, {\n        description: 'Global default rate limiter. \"off\": only routes tagged with rateLimitPolicy() are limited. \"on\": every named-middleware route gets the default limit too (opt out per route with .skip([\\'rateLimit\\'])). Health/SSE/WebSocket endpoints are always exempt. Overridden by defineServerConfig().rateLimit({ mode }).',\n        default: 'off',\n    }),\n\n    RATE_LIMIT_DEFAULT_LIMIT: envNumber({\n        description: 'Max requests per window for the global default limiter (RATE_LIMIT_MODE=on), counted per route and per client IP.',\n        default: 100,\n        examples: [60, 100, 300],\n    }),\n\n    RATE_LIMIT_DEFAULT_WINDOW_MS: envNumber({\n        description: 'Window length in milliseconds for the global default limiter.',\n        default: 60000,\n        examples: [1000, 60000],\n    }),\n\n    RATE_LIMIT_FAIL_CLOSED: envBoolean({\n        description: 'When the cache (Redis/Valkey) backing the limiter is unavailable, reject with 429 instead of counting in-process. Default false: the limiter falls back to per-process counters, so limits still apply — but the effective limit multiplies by the instance count, since each process counts alone. Set true only where a shared count is required and refusing traffic is preferable to a looser one.',\n        default: false,\n    }),\n\n    // ========================================================================\n    // Outbound request safety (SSRF)\n    // ========================================================================\n\n    SAFE_FETCH_BLOCK_PRIVATE_IPS: envBoolean({\n        description: 'Default for safeFetch (@spfn/core/security): block outbound requests that resolve to private/reserved IP ranges, including the cloud metadata address. Keep true in production; set false only for trusted internal-network calls in development. Overridden by defineServerConfig().outboundFetch({ blockPrivateIps }).',\n        default: true,\n    }),\n});\n","/**\n * Core Package Configuration\n *\n * @example\n * ```typescript\n * import { registry } from '@spfn/core/config';\n *\n * const env = registry.validate();\n * console.log(env.DB_POOL_MAX);\n * ```\n *\n * @module config\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { coreEnvSchema } from './schema';\n\n/**\n * Core environment schema\n */\nexport { coreEnvSchema as envSchema } from './schema';\n\n/**\n * Environment registry\n *\n * @example\n * ```typescript\n * // Reset for testing\n * registry.reset();\n * ```\n */\nexport const registry = createEnvRegistry(coreEnvSchema);\n\n/**\n * Validated environment configuration\n */\nexport const env = registry.validate();\n"]}

package/dist/contract/index.d.ts

@@ -1,7 +1,7 @@
-import { R as Router } from '../router-ukNdAZcN.js';
-import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-Bvvig_tT.js';
-export { d as CompatibilityPolicy, e as ContractRequest, f as ContractViolationKind, J as JsonSchema } from '../types-Bvvig_tT.js';
-import '../define-middleware-DfDP39Nq.js';
+import { R as Router } from '../router-Cy7rAfmj.js';
+import { C as ContractDocument, a as ContractViolation, b as ContractOperation, c as ContractSnapshot } from '../types-CfYVhIQ9.js';
+export { d as CompatibilityPolicy, e as ContractRequest, f as ContractViolationKind, J as JsonSchema } from '../types-CfYVhIQ9.js';
+import '../define-middleware-CVKgqo8S.js';
 import 'hono';
 import '@sinclair/typebox';
 import 'hono/utils/http-status';

package/dist/db/index.d.ts

@@ -246,7 +246,7 @@ declare function getDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase
  * // Set custom database instances (testing)
  * const writeClient = postgres('postgresql://primary:5432/mydb');
  * const readClient = postgres('postgresql://replica:5432/mydb');
- * setDatabase(drizzle(writeClient), drizzle(readClient));
+ * setDatabase(drizzle({ client: writeClient }), drizzle({ client: readClient }));
  *
  * // Clear instances (not recommended - use closeDatabase() instead)
  * setDatabase(undefined, undefined);