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

package/README.md

@@ -43,10 +43,12 @@ Next.js owns the frontend, Drizzle owns the SQL, and your services own the rules
 
 ```bash
 pnpm add @spfn/core@beta drizzle-orm@1.0.0-rc.4 postgres pg
-# optional peer: next ^16.2.11   (only for the Next.js bridge)
+# optional peer: next ^16.4.1   (only for the Next.js bridge)
+# optional peer: react ^18 || ^19 (only for @spfn/core/state/react)
 ```
 
-Node `>=20.0.0`. ESM only.
+Node `^22.23.4 || ^24.22.1 || >=26.12.1` — earlier releases lack the fix for
+CVE-2026-111497, and Node 20 reached end of life without one. ESM only.
 
 > **Declare Drizzle and the Postgres drivers in your own app, not just in SPFN.**
 > `@spfn/core` takes `drizzle-orm` as a peer dependency, and Drizzle changes how it
@@ -122,8 +124,9 @@ the route map the RPC proxy needs — and nothing else.
 5. **Mount the RPC proxy** in Next.js as the `app/api/rpc/[routeName]/route.ts`
    catch-all. The browser only ever sends `GET` (no body) or `POST` (body or formData)
    to `/api/rpc/{routeName}`; the proxy looks up `routeMap[routeName]`, substitutes
-   `:params`, and forwards with the real method. Package route maps (`authRouteMap`,
-   `eventRouteMap`) merge into the same map.
+   `:params`, and forwards with the real method. The generated map already carries the
+   routes of the packages the app router mounts with `.packages()`; `eventRouteMap` is
+   merged by hand, being a constant rather than a mounted router.
 6. **Call it** through `createApi<AppRouter>()`. The client is a `Proxy` over the
    `AppRouter` type — typed in and out, with no runtime cost for the types. Errors
    arrive as `ApiError`, or as the original error class when that class is registered in
@@ -185,18 +188,144 @@ import type { AppRouter } from '@/server/router';
 
 export const api = createApi<AppRouter>();
 
-// anywhere — server component, client component, or server action:
+// the same client in a Server Component, a Client Component or a Server Action:
 const user = await api.getUser.call({ params: { id: '123' } });    // typed { id, name }
 const made = await api.createUser.call({ body: { name: 'A' } });
 ```
 
+That the client is isomorphic does not make the three callers interchangeable. **A page's
+initial data is awaited in the Server Component**, where
+`api.getUser.fetchOptions({ next: { revalidate, tags } }).call(…)` participates in
+Next.js caching and reaches the backend without a browser round trip. Fetching that same
+first paint from a `'use client'` component inside a `useEffect` is the anti-pattern: it
+ships a loading state and a second network hop for data the server already had. Client
+Components and Server Actions are for what happens after the first paint — interaction
+and mutation. Cache tags, revalidation and SSR cookie forwarding are in
+[the Next.js bridge docs](https://superfunction.xyz/docs/packages/core/nextjs).
+
+---
+
+## How does a repository talk to the database?
+
+Through `BaseRepository`. Extending it gives a repository two transaction-aware
+connections — `this.db` (write/primary) and `this.readDb` (the replica, when one is
+configured) — plus the CRUD set as protected methods.
+
+```typescript
+// server/repositories/order.ts
+import { BaseRepository } from '@spfn/core/db';
+import { desc } from 'drizzle-orm';
+import { orders } from '../entities/order';
+
+export class OrderRepository extends BaseRepository
+{
+    findRecentFor(userId: string)
+    {
+        return this._findMany(orders, { where: { userId }, orderBy: desc(orders.createdAt) });
+    }
+
+    place(data: { userId: string; total: number })
+    {
+        return this._create(orders, data);
+    }
+}
+
+export const orderRepo = new OrderRepository();
+```
+
+Handlers never import drizzle query builders; repositories do. `_findMany` reads through
+`this.readDb`, `_create` writes through `this.db`, and both getters resolve to the active
+transaction's connection when there is one — so the same method is correct inside a
+transaction and outside it. When a helper cannot express a query, drop to
+`this.readDb.select()…` inside the repository rather than in the handler. The full
+protected CRUD set is in [src/db](./src/db/README.md).
+
+---
+
+## Where do transactions and their side effects go?
+
+`Transactional()` covers the route case — commit on return, rollback on throw. Two rules
+decide the rest.
+
+**Nothing takes a `tx` parameter.** The transaction travels in AsyncLocalStorage, so
+`this.db` inside a repository already resolves to it. A service that accepts `tx` and
+threads it downward re-implements propagation that already happened, and the first caller
+that forgets to pass it writes outside the transaction. For a service, script or job with
+no route around it, open one with `runInTransaction(fn, options?)`;
+`runWithTransaction(tx, txId, fn)` is the lower-level primitive that binds an existing
+Drizzle transaction into the context.
+
+**Side effects go on the commit hooks, not inline.** An event emitted or a mail sent from
+inside the transaction still went out when the transaction later rolls back.
+
+| Hook | When it runs | What it is for |
+|---|---|---|
+| `onBeforeCommit(fn)` | Inside the still-open transaction, just before commit — a throw aborts and rolls back | Last-moment invariant checks, and statements that must land in the same commit |
+| `onAfterCommit(fn)` | After the root transaction commits, outside the transaction context; errors are logged, never thrown | Events, mail, cache invalidation — anything the outside world observes |
+| `onAfterRollback(fn)` | After the root transaction rolls back, before the causing error propagates; errors are logged, never thrown | Undoing external work that cannot roll itself back, such as an object already uploaded |
+
+All three import from `@spfn/core/db`, can be registered anywhere inside the transaction,
+and bubble to the **root** transaction — a nested block's callbacks fire on the outermost
+outcome, not on a savepoint's.
+
+```typescript
+import { runInTransaction, onAfterCommit } from '@spfn/core/db';
+
+export async function placeOrder(input: { userId: string; total: number })
+{
+    return runInTransaction(async () =>
+    {
+        const order = await orderRepo.place(input);   // no tx argument, at any depth
+        onAfterCommit(() => orderPlacedEvent.emit({ orderId: order.id }));
+
+        return order;
+    });
+}
+```
+
+---
+
+## What else can defineServerConfig configure?
+
+`.port()` and `.routes()` are the two every app calls. The rest of the builder is how an
+app wires its infrastructure without touching the server's boot sequence. Every method
+returns the builder; `.build()` ends the chain.
+
+| Method | What it configures |
+|---|---|
+| `.port(n)` / `.host(s)` | Where the server listens |
+| `.routes(router)` | The `defineRouter` router to mount, with its own `.use()` and `.packages()` |
+| `.jobs(router, config?)` | Background jobs — a `defineJobRouter`, plus pg-boss options |
+| `.events(router, config?)` | SSE streaming — a `defineEventRouter`, served at `GET /events/stream` |
+| `.websockets(router, config?)` | Bidirectional WebSockets — a `defineWSRouter`, served at `WS /ws` |
+| `.workflows(router, config?)` | `@spfn/workflow` orchestration; the engine starts once the database is ready |
+| `.lifecycle(hooks)` | Boot and shutdown hooks. Callable more than once; hooks run in registration order |
+| `.migrations(opts)` | The migration boot gate — `{ allowPending: true }` lets a server start behind its migrations |
+| `.database(opts)` | Connection and pool settings |
+| `.infrastructure(opts)` | Which infrastructure is initialized at boot |
+| `.healthCheck(opts)` | The health endpoint |
+| `.serverTime(clock)` | The clock behind `GET /_core/time`; normally left at the default |
+| `.middleware(opts)` | The built-in middleware — `ErrorHandler`, `RequestLogger` |
+| `.use(handlers)` | Additional global Hono middleware |
+| `.middlewares(named)` | Global middleware under names, so a route can `.skip([...])` it |
+| `.cors(opts)` | CORS |
+| `.rateLimit(opts)` | A global default limiter plus the named policies routes resolve against |
+| `.proxyGuard(opts)` | Trusted-proxy signature and origin verification, resolved to a `clientType` |
+| `.outboundFetch(opts)` | The SSRF policy `safeFetch` applies to outbound calls |
+| `.timeout(opts)` / `.shutdown(opts)` | Request timeouts and graceful shutdown |
+| `.debug(bool)` | Debug logging |
+
+The options each one takes are in [src/server](./src/server/README.md).
+
 ---
 
 ## Which import path do I use for what?
 
 There is **no root barrel**: `import … from '@spfn/core'` does not resolve. Every symbol
 comes from a subpath, and the table below is the complete public surface — one row per
-entry in `package.json` `exports`. Each module has its own README with the API detail.
+entry in `package.json` `exports`, with a single exclusion: `./client` is still listed in
+`exports` but the build no longer emits it, so it has no row (see [Pitfalls](#pitfalls)).
+Each module has its own README with the API detail.
 
 | Import path | Purpose | Doc |
 |-------------|---------|-----|
@@ -207,16 +336,17 @@ entry in `package.json` `exports`. Each module has its own README with the API d
 | `@spfn/core/nextjs/server` | Server-only: `createRpcProxy({ routeMap })`, `registerInterceptors`. Uses `next/headers`. | [src/nextjs](./src/nextjs/README.md) |
 | `@spfn/core/db` | PostgreSQL through Drizzle: CRUD helpers, `BaseRepository`, schema helpers, transactions, Postgres error mapping. One entry point for all of it. | [src/db](./src/db/README.md) |
 | `@spfn/core/db` → manager | Connection lifecycle, pool, primary/replica, health check, reconnect (`initDatabase`, `getDatabase`). Re-exported from `@spfn/core/db`. | [src/db/manager](./src/db/manager/README.md) |
-| `@spfn/core/db` → migrations | Which migrations each installed function package ships, and which the database has applied (`collectMigrationStatus`, `discoverFunctionMigrations`). What `spfn db status`, the boot gate and health all read. Re-exported from `@spfn/core/db`. | [src/db/migrations](./src/db/migrations/index.ts) |
+| `@spfn/core/db` → migrations | Which migrations each installed function package ships, and which the database has applied (`collectMigrationStatus`, `discoverFunctionMigrations`). What `spfn db status`, the boot gate and health all read. Re-exported from `@spfn/core/db`. | [src/db/migrations](https://github.com/fxylabs/spfn/blob/main/packages/core/src/db/migrations/index.ts) |
 | `@spfn/core/db` → schema | Drizzle column helpers (`id`, `uuid`, `timestamps`, `foreignKey`, `enumText`, `typedJsonb`, `softDelete`, …). Re-exported from `@spfn/core/db`. | [src/db/schema](./src/db/schema/README.md) |
 | `@spfn/core/db` → transaction | `Transactional()` middleware and `runInTransaction`; the transaction reaches every repository through AsyncLocalStorage. Re-exported from `@spfn/core/db`. | [src/db/transaction](./src/db/transaction/README.md) |
 | `@spfn/core/middleware` | Built-in Hono middleware: `ErrorHandler`, `RequestLogger` and its masking helper. | [src/middleware](./src/middleware/README.md) |
 | `@spfn/core/errors` | Serializable HTTP and database error classes, plus `ErrorRegistry` so an error survives the trip to the client as its own class. | [src/errors](./src/errors/README.md) |
 | `@spfn/core/security` | `safeFetch` — a drop-in `fetch` hardened against SSRF, including DNS rebinding, by pinning the connection to a validated IP. | [src/security](./src/security/README.md) |
-| `@spfn/core/authz` | Ownership guards. `requireOwner(resource, userId)` makes "load it, then check it belongs to the requester" one call, so a handler cannot forget it. | [src/authz/index.ts](./src/authz/index.ts) |
+| `@spfn/core/authz` | Ownership guards. `requireOwner(resource, userId)` makes "load it, then check it belongs to the requester" one call, so a handler cannot forget it. | [src/authz/index.ts](https://github.com/fxylabs/spfn/blob/main/packages/core/src/authz/index.ts) |
 | `@spfn/core/env` | Schema-based environment validation, isomorphic. | [src/env](./src/env/README.md) |
 | `@spfn/core/env/loader` | The **server-only** `.env` file loader (uses `node:fs`). | [src/env](./src/env/README.md) |
 | `@spfn/core/config` | `@spfn/core`'s own validated env config (`env`, `envSchema`, `registry`), built on `@spfn/core/env`. | [src/config](./src/config/README.md) |
+| `@spfn/core/app-config` | Reads `spfn.config.js` — the one committed place that says which ports and host the app is served on (`loadAppConfig`, `resolvePorts`, `resolveHost`, `PORT_DEFAULTS`), and where the app's env schema modules are (`env.schemas`, read by `spfn env` / `spfn secret`). Deliberately side-effect free, so the CLI can import it before an app's environment exists. | [src/app-config/index.ts](https://github.com/fxylabs/spfn/blob/main/packages/core/src/app-config/index.ts) |
 | `@spfn/core/logger` | Structured singleton `logger` with child loggers and level masking. No dependencies. | [src/logger](./src/logger/README.md) |
 | `@spfn/core/cache` | Valkey/Redis singleton over ioredis (`getCache`, `getCacheRead`). Degrades to disabled rather than throwing. | [src/cache](./src/cache/README.md) |
 | `@spfn/core/job` | Background jobs on pg-boss: a fluent `job()` builder, cron, run-once, event-driven, `defineJobRouter`. | [src/job](./src/job/README.md) |
@@ -225,8 +355,13 @@ entry in `package.json` `exports`. Each module has its own README with the API d
 | `@spfn/core/event/sse/client` | Browser SSE client (`EventSource`). | [src/event](./src/event/README.md) |
 | `@spfn/core/event/ws` | Server-side WebSocket handler. Server only; needs the optional `ws` dependency. | [src/event](./src/event/README.md) |
 | `@spfn/core/event/ws/client` | Browser WebSocket client. | [src/event](./src/event/README.md) |
+| `@spfn/core/state` | A server-owned state declared once (`defineState`, `defineStateRouter`) derives its read, write and snapshot routes and its SSE event; the app emits `state.changed` after a commit. Server only. | [src/state](./src/state/README.md) |
+| `@spfn/core/state/client` | The browser side of a state router, typed from `typeof states` (type-only import) and told the rest by the snapshot's manifest: `createStateClient` reads, writes and snapshots through the derived routes, keeps one SSE stream for every state, and orders snapshots against frames by `at`. Framework-neutral, no React. | [src/state](./src/state/README.md#browser) |
+| `@spfn/core/state/react` | `useServerState(client, id, key?)` — a component's view of one state through `useSyncExternalStore`, with `write` on a state that has one. Needs the optional `react` peer. | [src/state](./src/state/README.md#browser) |
 | `@spfn/core/codegen` | The codegen orchestrator and the built-in generators: `@spfn/core:route-map` for the proxy's route map, `@spfn/core:contract` for the client contract. | [src/codegen](./src/codegen/README.md) |
 | `@spfn/core/contract` | Route contracts for clients that ship separately: collect, snapshot, and the build gate that refuses a breaking change. | [src/contract](./src/contract/README.md) |
+| `@spfn/core/ops` | The operations surface `spfn ops` drives: `opsRoute`, `createOpsRouter`, `defineOpsModule`, and the manifest the CLI discovers commands from. Structure only — the router is always authenticated, and token verification lives in `@spfn/auth`. | [How do I operate the app from the terminal?](#how-do-i-operate-the-app-from-the-terminal) |
+| `@spfn/core/surface` | `defineSurface`: a command surface on any namespace — the same authenticated router, manifest and modules `@spfn/core/ops` is on `/_ops`, for a caller other than an operator. | [Can a second surface sit beside `/_ops`?](#can-a-second-surface-sit-beside-_ops) |
 
 `db/manager`, `db/schema` and `db/transaction` are **not** package subpaths of their own.
 They are internal modules re-exported by `@spfn/core/db` — import their symbols from
@@ -359,6 +494,39 @@ probe depends on, and a probe reaches it unauthenticated. An app with `src/serve
 
 ---
 
+## How does a client synchronize with the server clock?
+
+Call `GET /_core/time` before minting a timestamped proof. It is a built-in,
+unauthenticated and session-free operation registered before application middleware and
+routes:
+
+```json
+{ "serverTimeMillis": 1750000000123 }
+```
+
+The response is a closed contract: `serverTimeMillis` is an integer Unix epoch in
+milliseconds and no additional fields are declared. It always carries
+`Cache-Control: no-store`; a cached clock reading is not a synchronization point.
+
+The value is trustworthy only when the transport is trustworthy. Production clients must
+call the endpoint over HTTPS and validate the server certificate. The endpoint does not
+sign its response, compensate for network latency, choose an authentication skew margin,
+or define client retry and persistence policy — those belong to the consuming protocol.
+
+Tests can inject an exact clock without replacing global time:
+
+```typescript
+const app = await createServer(defineServerConfig()
+    .serverTime({ clock: { now: () => 1750000000123 } })
+    .build());
+```
+
+`CORE_TIME_ROUTE`, `CORE_TIME_PATH`, `ServerTimeResponseSchema` and the
+`ServerTimeResponse` type are exported from `@spfn/core/server` for separately deployed
+client-contract exporters to consume from the same wire definition.
+
+---
+
 ## Can I deploy this to Vercel?
 
 Yes, and it is a first-class target rather than a workaround. From your app:
@@ -483,6 +651,61 @@ spfn ops call listSignups --query limit=50            # invoke one
 spfn ops call listSignups --describe                  # print its usage (--json for raw schemas)
 ```
 
+### Can a package ship ops commands?
+
+It can describe them. Whether they are reachable is your application's decision, made in
+the `createOpsRouter` call — installing a package never adds anything to your ops surface.
+Available from **0.3.0-beta.5**.
+
+```typescript
+// in the package
+export const ledgerOpsModule = defineOpsModule({
+    id: 'ledger',
+    source: '@acme/ledger',
+    contractVersion: '1.0.0',
+    summary: 'Ledger diagnostics',
+    commands: {
+        verify: {
+            summary: 'Verify ledger invariants',
+            effect: 'read',                                  // read | write | destructive
+            scopes: ['ledger:read'],
+            route: opsRoute.get('/ledger/verify').handler(verifyLedger),
+        },
+    },
+});
+
+// in the application — nothing is mounted until this line names it
+export const opsRouter = createOpsRouter({ listSignups }, {
+    auth: opsTokenAuth,
+    authorize: requireOpsScope,
+    modules: [ledgerOpsModule],
+});
+```
+
+A module command is named `<module>.<command>` (`ledger.verify`) and its route must live
+under `/_ops/<module>/`. The scopes it declares become a server-side guard, run after
+authentication — `authorize` is required as soon as any module is mounted, and it is passed
+in rather than imported so core stays independent of `@spfn/auth`.
+
+What is refused at definition time: a path that could decode its way out of the module's
+namespace, two commands in one module that could answer the same URL, and an app route that
+overlaps a mounted module's command. That last one matters because the alternative is a
+surface where which command answers depends on route registration order.
+
+The manifest gains a `modules` array and per-command `module`, `summary`, `effect` and
+`scopes`. All of it is additive — an app that mounts no modules serves exactly the v1
+manifest it served before.
+
+An app's own ops routes may declare `.effect()` and `.summary()` too, and the manifest
+carries both for that command. On `/_ops` they are optional: a route declaring neither is
+announced exactly as before.
+
+```bash
+spfn ops modules                                      # what is mounted, and from where
+spfn ops list --module ledger                         # just that module's commands
+spfn ops call ledger.compact --yes                    # effect=destructive needs this
+```
+
 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` against the running app
 — the CLI signs in as an administrator, so issuance needs no database access. On macOS the
@@ -490,6 +713,74 @@ CLI keeps the token in the keychain (`spfn ops token store`), and resolution ord
 `--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.
 
+### Can a second surface sit beside `/_ops`?
+
+Yes. `/_ops` is one command surface; `defineSurface` from `@spfn/core/surface` builds
+another on a namespace of your choosing, for a caller that is not an operator — a service
+holding a token some issuer signed, say. It is the same structure: a `route` with the
+namespace applied, auth injected into every command, a manifest at `<namespace>/_manifest`
+registered first, and modules mounted only when you name them. `createOpsRouter` is
+`defineSurface({ namespace: '/_ops', ... }).router(...)`.
+
+```typescript
+// src/server/app-surface.ts
+import { Type } from '@sinclair/typebox';
+import { defineSurface } from '@spfn/core/surface';
+import { signedTokenAuth } from '@spfn/auth/server';
+
+export const app = defineSurface({
+    namespace: '/_app',                                     // required
+    auth: signedTokenAuth({                                 // required
+        keysUrl: 'https://issuer.example/.well-known/keys',
+        iss: 'https://issuer.example',
+        aud: 'my-app',
+    }),
+    manifest: 'public',                                     // 'authenticated' (default) | 'public'
+});
+
+export const pageAdd = app.route.post('/pages')            // POST /_app/pages
+    .input({ body: Type.Object({ title: Type.String() }) })
+    .effect('write')                                        // required: read | write | destructive
+    .summary('Add a page to the blueprint')                 // optional, at most 500 characters
+    .handler(async (c) => pagesRepository.add((await c.data()).body.title));
+
+// src/server/router.ts — both surfaces, side by side
+export const appRouter = defineRouter({ ... }).packages([app.router({ pageAdd }), opsRouter]);
+```
+
+- **Namespace.** An absolute path of `[A-Za-z0-9_-]` segments with no trailing slash —
+  `/_app`, `/machine/v1`. Anything else (`app`, `/_app/`, `/`, a `%`, a `:param`) is refused
+  at `defineSurface`.
+- **Manifest.** Served at `<namespace>/_manifest` under the reserved route name
+  `get<Namespace>Manifest` — `getAppManifest` for `/_app`, `getOpsManifest` for `/_ops`,
+  `getappManifest` for `/app`. The namespace is encoded one-to-one (`_x` → `X`; any other
+  `_`, `-`, `/` or uppercase letter is escaped with `_`), so two surfaces never register one
+  name. Two surfaces on one namespace are refused by `.packages()`. `manifest: 'public'`
+  drops `auth` from that one route and skips a server-level `auth` middleware on it, so a
+  caller can discover commands before it holds a token; every command stays behind `auth`
+  regardless.
+- **`authorize`.** Optional, `(command) => middleware | undefined`, called once per command
+  (module commands included) when the router is built. The middleware runs after `auth` and
+  before the command's own: `[auth, authorize?, ...group, ...own]`. Required as soon as a
+  module is mounted. A guard named like `auth` or like one of the command's group or own
+  middlewares is refused: registration keeps one middleware per name, so the other one would
+  never run.
+- **Effect.** Every app command on a `defineSurface` surface declares `.effect()` on its
+  route; `router()` refuses one that does not, naming the command, so a client never
+  receives a command whose effect it cannot know. `/_ops` routes may declare it and need
+  not. The manifest announces `effect` and `summary` beside the command, and `authorize`
+  receives them on the command it is given. A module command's own declaration wins over its
+  route's: a route `.effect()` that disagrees with it is refused.
+- **Modules.** A module is validated against the namespace of the surface that mounts it —
+  its commands must live under `<namespace>/<id>/`. Write one for a surface with
+  `defineSurfaceModule(module, '/_app')`; a module written for `/_ops` mounted on `/_app` is
+  refused, and the message names the namespace.
+- **Errors.** Every refusal is a `SurfaceError`. `@spfn/core/ops` exports the same class as
+  `OpsRouterError`, so `instanceof` holds under either name.
+
+The client for any surface is the CLI's library export,
+[`spfn/surface`](../cli/README.md#can-i-call-a-surface-from-my-own-code).
+
 ---
 
 ## How is this different from NestJS or tRPC?
@@ -565,7 +856,7 @@ There is no `.` entry in `exports` — by design. Subpaths keep server-only code
 client bundles, which a single barrel file cannot do.
 
 **Which Node version?**
-`>=20.0.0`. The package is ESM only.
+`^22.23.4 || ^24.22.1 || >=26.12.1`. The package is ESM only.
 
 **Where do my business rules go?**
 In services and repositories, not in route handlers. A handler validates, calls, and
@@ -579,9 +870,10 @@ way so the endpoint never reveals that someone else's record exists.
 
 Other SPFN packages build on `@spfn/core`:
 
-- [`@spfn/auth`](../auth/README.md) — sessions, social login and RBAC. Exports
-  `authRouteMap` and registers proxy interceptors automatically; merge its route map into
-  `createRpcProxy`.
+- [`@spfn/auth`](../auth/README.md) — sessions, social login and RBAC. Mount `authRouter`
+  with `.packages()` and its routes are in the app's generated map; the package registers
+  proxy interceptors automatically. (`authRouteMap` is still exported, and merging it is
+  now a no-op.)
 - [`@spfn/mcp`](../mcp/README.md) — exposes your operations as MCP tools, so an agent can
   run them instead of you building an admin dashboard.
 - `@spfn/i18n`, `@spfn/storage`, `@spfn/notification`, `@spfn/cms`, `@spfn/monitor`,

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

@@ -28,10 +28,48 @@ interface SpfnPorts {
     /** SPFN API server. */
     server?: number;
 }
+/**
+ * Where the app's own environment schema lives.
+ *
+ * Read by the CLI (`spfn env`, `spfn secret`), which cannot otherwise find an
+ * app's variables: a package's schema sits at `<package>/config`, an app's
+ * sits wherever the app put it.
+ */
+interface SpfnEnvConfig {
+    /**
+     * Modules that export `envSchema`, as paths relative to the project root —
+     * e.g. `['src/server/config/env.config.ts']`. TypeScript and the
+     * tsconfig path aliases it imports through are supported.
+     */
+    schemas?: string[];
+    /** What `spfn env audit` scans. */
+    audit?: SpfnEnvAuditConfig;
+}
+/**
+ * The files `spfn env audit` reads, as globs relative to the project root.
+ *
+ * `node_modules`, build output, `*.d.ts` files and symbolic links are never
+ * scanned, whatever the globs say.
+ */
+interface SpfnEnvAuditConfig {
+    /**
+     * Directories or globs to scan — e.g. `['src', 'scripts/*.ts']`.
+     *
+     * @default ['src']
+     */
+    include?: string[];
+    /**
+     * Directories or globs to leave out — e.g. `['src/legacy/**']`. A file left
+     * out may read `process.env` directly, and names it reads do not count as read.
+     */
+    ignore?: string[];
+}
 interface SpfnAppConfig {
     ports?: SpfnPorts;
     /** Host the SPFN API server binds. */
     host?: string;
+    /** The app's environment schema modules, and what `spfn env audit` scans. */
+    env?: SpfnEnvConfig;
     /** Deployment settings — untouched by this module, kept so the type is whole. */
     [key: string]: unknown;
 }
@@ -93,4 +131,4 @@ declare function resolveServerAddress(config: SpfnAppConfig, deprecated?: {
     host: string;
 };
 
-export { HOST_DEFAULT, PORT_DEFAULTS, type SpfnAppConfig, type SpfnPorts, loadAppConfig, resolveHost, resolvePorts, resolveServerAddress };
+export { HOST_DEFAULT, PORT_DEFAULTS, type SpfnAppConfig, type SpfnEnvAuditConfig, type SpfnEnvConfig, type SpfnPorts, loadAppConfig, resolveHost, resolvePorts, resolveServerAddress };

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

@@ -1 +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"]}
+{"version":3,"sources":["../../src/app-config/index.ts"],"names":[],"mappings":";;;;;AAwGO,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\n/**\n * Where the app's own environment schema lives.\n *\n * Read by the CLI (`spfn env`, `spfn secret`), which cannot otherwise find an\n * app's variables: a package's schema sits at `<package>/config`, an app's\n * sits wherever the app put it.\n */\nexport interface SpfnEnvConfig\n{\n    /**\n     * Modules that export `envSchema`, as paths relative to the project root —\n     * e.g. `['src/server/config/env.config.ts']`. TypeScript and the\n     * tsconfig path aliases it imports through are supported.\n     */\n    schemas?: string[];\n\n    /** What `spfn env audit` scans. */\n    audit?: SpfnEnvAuditConfig;\n}\n\n/**\n * The files `spfn env audit` reads, as globs relative to the project root.\n *\n * `node_modules`, build output, `*.d.ts` files and symbolic links are never\n * scanned, whatever the globs say.\n */\nexport interface SpfnEnvAuditConfig\n{\n    /**\n     * Directories or globs to scan — e.g. `['src', 'scripts/*.ts']`.\n     *\n     * @default ['src']\n     */\n    include?: string[];\n\n    /**\n     * Directories or globs to leave out — e.g. `['src/legacy/**']`. A file left\n     * out may read `process.env` directly, and names it reads do not count as read.\n     */\n    ignore?: string[];\n}\n\nexport interface SpfnAppConfig\n{\n    ports?: SpfnPorts;\n\n    /** Host the SPFN API server binds. */\n    host?: string;\n\n    /** The app's environment schema modules, and what `spfn env audit` scans. */\n    env?: SpfnEnvConfig;\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"]}