@spfn/core 0.3.0-beta.15 → 0.3.0-beta.17

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spfn/core",
-    "version": "0.3.0-beta.15",
+    "version": "0.3.0-beta.17",
     "description": "Full-stack TypeScript backend for Next.js: file-based typed routes, Drizzle entities and repositories, PostgreSQL transactions and a generated end-to-end client, in one fixed vertical slice per feature",
     "type": "module",
     "exports": {
@@ -209,7 +209,7 @@
         "pg-boss": "^11.1.2",
         "postgres": "^3.4.0",
         "typescript": "^5.3.3",
-        "undici": "^7.29.0",
+        "undici": "^7.29.1",
         "zod": "^4.4.3"
     },
     "optionalDependencies": {

package/src/config/README.md

@@ -81,13 +81,18 @@ env.SPFN_API_URL;  // read + validated HERE; throws if missing (required) or inv
 
 Consequences:
 
-- A missing **required** variable (`SPFN_API_URL`, `NEXT_PUBLIC_SPFN_API_URL`) does not
+- A missing **required** variable (`SPFN_API_URL`) does not
   throw on import — it throws on first access (`Error('Environment validation failed')`).
 - You may import `env` before `loadEnv()` runs; values are picked up lazily.
 - For an **eager** all-at-once check (CI / startup gate), call `registry.validateAll()`
   (returns `{ errors, warnings }`) or pass `registry` to `validateAllEnv([...])` from
   `@spfn/core/env`. `SKIP_ENV_VALIDATION=true` skips only the lazy `required` check, not
   these eager checks.
+- **The SPFN server runs that eager check at boot.** `startServer` validates this
+  registry — plus any registries the app hands over with
+  `defineServerConfig().env({ registries })` — before it listens, and exits with code 1
+  listing each failing key (never a value). See
+  [Boot-time check](../env/README.md#boot-time-check-the-server).
 
 See [@spfn/core/env](../env/README.md) for the full registry / proxy / `SKIP_ENV_VALIDATION`
 semantics — this module inherits all of it unchanged.
@@ -221,24 +226,25 @@ validator **throw on access** if the value is present but malformed.
 | Variable | Type | Required | Validator | Notes |
 |----------|------|----------|-----------|-------|
 | `SPFN_API_URL` | `string` (`envUrl`) | **Yes** | URL | `nextjs: true`; Next.js → backend |
-| `NEXT_PUBLIC_SPFN_API_URL` | `string` (`envUrl`) | **Yes** | URL | `nextjs: true`; client-exposed |
-| `SPFN_APP_URL` | `string` (`envUrl`) | No | URL | `nextjs: true`; SPFN server → Next.js |
+| `NEXT_PUBLIC_SPFN_API_URL` | `string` (`envUrl`) | No | URL | `nextjs: true`; client-exposed, inlined by Next.js at build; the server uses `SPFN_API_URL` |
+| `SPFN_APP_URL` | `string` (`envUrl`) | No (no default) | URL | `nextjs: true`; SPFN server → Next.js |
 | `RPC_PROXY_TIMEOUT` | `number` | No (default `120000`) | — | `nextjs: true`; keep < `FETCH_HEADERS_TIMEOUT` |
 
-> `SPFN_API_URL` and `NEXT_PUBLIC_SPFN_API_URL` are both `envUrl` and both **required** —
-> a missing or non-URL value throws on first access of that property.
+> `SPFN_API_URL` is **required** — a missing or non-URL value throws on first access.
+> `NEXT_PUBLIC_SPFN_API_URL` is optional to the server, which falls back to `SPFN_API_URL`;
+> set it wherever browser code needs the API URL. These three URLs are declared by
+> `@spfn/core` only — packages read them from `@spfn/core/config` rather than declaring them again.
 
 ---
 
 ## Pitfalls & anti-patterns
 
 - **Don't expect validation on import.** Importing `@spfn/core/config` validates nothing;
-  the proxy validates each variable on property access. A missing `SPFN_API_URL` /
-  `NEXT_PUBLIC_SPFN_API_URL` throws when you *read* it, not when you import `env`. For a
-  startup gate, call `registry.validateAll()` explicitly.
-- **`SPFN_API_URL` and `NEXT_PUBLIC_SPFN_API_URL` are both required and both URLs.** Setting
-  only one of them will throw on access of the other. They are validated as URLs (`envUrl`),
-  so a non-URL string fails too.
+  the proxy validates each variable on property access. A missing `SPFN_API_URL` throws
+  when you *read* it, not when you import `env`. The SPFN server does check it eagerly at
+  boot (`startServer` / `createServerlessApp`), so a server process needs it set.
+- **The three URLs are validated as URLs (`envUrl`).** A non-URL string in `SPFN_API_URL`,
+  `NEXT_PUBLIC_SPFN_API_URL` or `SPFN_APP_URL` fails on access and at boot.
 - **Don't call `loadEnv()` inside Next.js.** Next.js already loads `.env*`. Calling it there
   (with `server: true`) would pull `.env.server` secrets into the Next.js process. In the
   **SPFN server** entry point you *do* call `loadEnv()` before touching `env`.
@@ -265,7 +271,8 @@ import { env, registry } from '@spfn/core/config';
 
 loadEnv();   // populate process.env from .env* (server includes .env.server)
 
-// Optional eager gate: fail fast on missing/invalid required vars at startup.
+// Eager gate for a custom entry point — startServer() already runs this check
+// (see "Boot-time check" in the env README), so an SPFN server needs none of it.
 const { errors, warnings } = registry.validateAll();
 for (const w of warnings) console.warn(`${w.key}: ${w.message}`);
 if (errors.length)
@@ -296,7 +303,7 @@ const apiUrl = env.SPFN_API_URL;          // required URL — throws if unset/in
 // Next.js — no loadEnv()
 import { env } from '@spfn/core/config';
 
-const apiUrl = env.NEXT_PUBLIC_SPFN_API_URL; // required URL, client-exposed
+const apiUrl = env.NEXT_PUBLIC_SPFN_API_URL; // optional URL, client-exposed
 ```
 
 ```typescript

package/src/env/README.md

@@ -160,6 +160,8 @@ CONFIG: envJson<{ host: string; port: number }>({
 | `sensitive` | `boolean` | Marks a secret; triggers a warning if `NEXT_PUBLIC_*` |
 | `examples` | `T[]` | Example values (metadata only) |
 | `nextjs` | `boolean` | File-separation hint (see below). Defaults to `true` for `NEXT_PUBLIC_*`, else `false` |
+| `layer` | `'environment' \| 'instance'` | Which deployment layer must supply the value (see below). Unset: may come from any layer |
+| `readBy` | `string[]` | Files that read the name under a computed key, relative to the project root — for `spfn env audit` (see below) |
 
 > There is **no** `category` option. Docs that show `category: '...'` are stale — passing
 > it is harmless (excess property) but it does nothing.
@@ -249,6 +251,137 @@ for (const w of result.warnings) {
 A single registry exposes the same via `registry.validateAll()` returning just
 `{ errors, warnings }`.
 
+Messages carry the key and the rule, never the value. For a `sensitive` key the validator's
+own message is replaced by `(value hidden — sensitive key)`, because a validator may echo its
+input; core's parsers describe the expected shape instead of quoting the input. An app
+validator on a non-sensitive key should do the same.
+
+### Boot-time check (the server)
+
+`startServer()` runs `validateAllEnv` right after loading the env files and the app's
+`server.config`, before it initializes infrastructure or listens. The list is `@spfn/core`'s
+registry plus the registries the app hands over in `server.config`:
+
+```typescript
+// src/server/config/env.config.ts
+export const envSchema = defineEnvSchema({ /* ... */ });
+export const envRegistry = createEnvRegistry(envSchema);
+export const env = envRegistry.validate();
+
+// src/server/server.config.ts
+import { envRegistry } from '@/server/config/env.config';
+
+export default defineServerConfig()
+    .env({ registries: [envRegistry] })
+    .build();
+```
+
+On failure it logs each key with its reason (never a value) and exits with code 1. A
+package's variables are checked only when the app passes a registry for them —
+`createEnvRegistry(envSchema)` over the schema the package exports from `./config`.
+
+- `SKIP_ENV_VALIDATION` does not apply: it relaxes the lazy proxy for build steps, and a
+  server about to serve is not a build step.
+- `createServerlessApp()` runs the same check and rejects its promise instead of exiting.
+- `createServer()` (the app factory both of them use) and `provisionInfrastructure()` do not
+  run it.
+- `@spfn/core` itself requires `SPFN_API_URL`, so the server process needs it set.
+  `NEXT_PUBLIC_SPFN_API_URL` is optional there: Next.js inlines it at build time and the
+  server falls back to `SPFN_API_URL`.
+
+### The app's schema in the CLI (`spfn.config.js` `env.schemas`)
+
+`spfn env` and `spfn secret` find a package's schema at `<package>/config`; an app's own
+schema can live anywhere, so `spfn.config.js` names it:
+
+```js
+// spfn.config.js
+export default {
+    env: {
+        schemas: ['src/server/config/env.config.ts'], // modules exporting `envSchema`
+    },
+};
+```
+
+Paths are relative to the project root; TypeScript and tsconfig path aliases are supported.
+Without `-p <package>`, the CLI reads these modules plus every installed `@spfn/*` package
+whose `./config` exports `envSchema`, and groups its output by source. A key two sources
+declare identically is listed once; two declarations that differ in type, `required` or
+`sensitive` are an error naming the key and both sources — one variable has one owner, and
+other packages read it from the owner's `env` instead of declaring it again.
+
+### Auditing the code against the list (`env.audit`, `readBy`)
+
+`spfn env audit` keeps the list and the code in step, and exits 1 on any finding. It prints
+`file:line  NAME  reason` — names only, never values — for:
+
+- **Direct reads.** `process.env.X`, `process.env['X']`, `process.env[expr]` and
+  `const { X } = process.env` (also through `process?.env` and `globalThis.process.env`).
+  Allowed in the modules named in `env.schemas`, in root-level `*.config.{js,cjs,mjs,ts}`
+  files and in files matching `env.audit.ignore`. `NODE_ENV` is allowed everywhere.
+- **Unused declarations.** A name in the app's own schemas that no scanned file outside the
+  schema modules reads — as a property (`env.X`), a destructured key (`const { X } = env`)
+  or a string literal `'X'`. Names an installed `@spfn/*` package also declares are read
+  inside that package and are not checked. Without `env.schemas` this check is skipped
+  with a notice.
+
+```js
+// spfn.config.js
+export default {
+    env: {
+        schemas: ['src/server/config/env.config.ts'],
+        audit: {
+            include: ['src'],             // default; directories or globs from the project root
+            ignore: ['src/**/*.test.ts'], // may read process.env; the names they read do not count
+        },
+    },
+};
+```
+
+`node_modules`, build output (`dist`, `build`, `out`, `.next`, …), `*.d.ts` files and
+symbolic links are never scanned. Sources are parsed with TypeScript, so a mention in a
+comment or a string is not a read.
+
+A name the code only reaches under a computed key — ``env[`${provider}_API_KEY`]`` — is
+invisible to the scan. List the files that read it in `readBy`:
+
+```typescript
+const schema = defineEnvSchema({
+    PAYMENT_API_KEY: envSecret({ description: 'Payment provider key', readBy: ['src/server/providers.ts'] }),
+});
+```
+
+The name passes when every listed file exists and is scanned; a listed file that does not
+exist, or that the audit does not scan, is a finding. The runtime ignores `readBy`.
+
+A name that appears only in a log message string counts as read — the string-literal rule
+cannot tell a message from a lookup key.
+
+### Deployment layers (`layer`)
+
+A deployed environment can run more than one instance — `staging` as `blue` and `green`,
+each with its own port, URLs and database. `layer` pins where a variable's value must come
+from, so `spfn secret export` can assemble one instance's env file and refuse a value that
+arrives from the wrong place. Unset, the value may come from any layer — a package schema
+leaves it unset, so an app can keep a value such as a session secret shared or give each
+instance its own:
+
+| Layer | Holds | Source |
+|-------|-------|--------|
+| `environment` | Values every instance of the environment shares — third-party API keys | `secrets/<env>.enc.json` |
+| `instance` | Values of one instance: its own secrets, or plain values the deploy script computes (port, URLs, database name) | `secrets/<env>.<instance>.enc.json`, or a `--with <file>` dotenv file |
+
+```typescript
+const schema = defineEnvSchema({
+    PAYMENT_API_KEY: envSecret({ description: 'Payment provider key', required: true, layer: 'environment' }),
+    DB_NAME: envString({ description: 'Database of this instance', required: true, layer: 'instance' }),
+});
+```
+
+A name declared `environment` found in an instance layer, a name declared `instance` found
+in the environment file, or any name found in two layers fails the export. The runtime ignores
+`layer`; it only steers the CLI.
+
 ### Fallback keys
 
 ```typescript
@@ -556,7 +689,10 @@ optional(parseRedisUrl);                                    // '' → undefined,
 - **`sensitive: true` + `NEXT_PUBLIC_` is wrong.** It only emits a warning, not an error —
   the secret is still exposed. Remove the prefix.
 - **`SKIP_ENV_VALIDATION` only skips the `required` check** (and only in the lazy proxy);
-  present values are still validated, and `validateAll()` ignores the flag entirely.
+  present values are still validated, and `validateAll()` — and with it the server's boot
+  check — ignores the flag entirely.
+- **A validator message must not contain the value.** Validation errors are logged. Throw
+  `'Must be a valid number'`, not `` `got: ${value}` ``.
 - **Removed API.** `getEnvVar`, `requireEnvVar`, `hasEnvVar`, `getEnvVars`,
   `loadEnvironment`, `namespace`/`useFolderStructure`/`customPaths`/`useCache` loader
   options, `env.get()`/`env.require()`, `getByCategory()`/`getAllSchemas()`,