spfn 0.2.0-beta.65 → 0.2.0-beta.67

package/README.md

@@ -5,6 +5,11 @@ architecture. It can scaffold either a core-only backend or a production baselin
 authentication, internationalization, and an agent-facing MCP endpoint, then runs the
 dev/build/start lifecycle, database tooling, RPC codegen, and environment validation.
 
+Consistent is the point rather than a nicety: what it scaffolds is one fixed shape per
+feature, so a coding agent has no architecture left to invent and the codebase does not
+acquire several. That problem has a name —
+[architecture drift](https://superfunction.xyz/architecture-drift).
+
 > Beta: install with the `@beta` tag (`spfn@beta`). The binary is `spfn`.
 
 ## Install
@@ -20,7 +25,8 @@ Or add it as a project dependency (`spfn init`/`spfn create` do this for you), t
 call it via `pnpm spfn <command>` / `npm run spfn:<script>`.
 
 Requirements: Node.js 18.18+ for bare mode, Node.js 20+ for full mode's MCP server,
-Next.js 15+ (App Router, `src/` dir), PostgreSQL (Redis optional).
+Next.js 16.2.11+ (App Router, `src/` dir), PostgreSQL 14+ (Redis optional). Next.js 15
+is not supported — see [the root README](../../README.md#what-do-i-need-installed).
 
 ## Usage
 
@@ -48,7 +54,7 @@ with `--pm`. In a pnpm workspace, `create` installs from the workspace root.
 ## Commands
 
 Registered top-level commands: `create`, `init`, `add`, `dev`, `build`, `start`,
-`codegen`, `db`, `env`, `key`, `setup`.
+`provision`, `codegen`, `contract`, `key`, `setup`, `db`, `env`, `secret`.
 
 ### `spfn create <name>`
 
@@ -101,6 +107,23 @@ How it works: if not already present it installs the package, then reads the pac
 function migrations to `DATABASE_URL`. If `DATABASE_URL` is unset, migration is skipped
 with a hint to run `spfn db push` later. Works with published and workspace packages.
 
+### `spfn add vercel`
+
+`vercel` is not a package — it is a built-in target, and the one argument to `add` that is
+not a scoped package name. It scaffolds the three files a Next.js + SPFN app needs to run
+its backend as Vercel Functions:
+
+| File | What it is |
+|------|------------|
+| `src/app/api/backend/[[...route]]/route.ts` | `hono/vercel` adapter, mounts the SPFN app under `/api/backend` |
+| `vercel.json` | build config (`pnpm spfn:build`) |
+| `.npmrc` | `@spfn` registry auth, reading `GITEA_NPM_TOKEN` from the environment — never committed |
+
+Existing files are never overwritten; they are reported and skipped. The runtime behind
+the adapter is `createServerlessApp()` from `@spfn/core/server`. Afterwards, point
+`SPFN_API_URL` at `https://<your-domain>/api/backend`, and make sure `hono` is a direct
+dependency of the app so `hono/vercel` resolves.
+
 ### `spfn dev`
 
 Starts the SPFN server + Next.js (and a codegen watcher). The server must report ready
@@ -176,6 +199,43 @@ export default defineConfig({
 });
 ```
 
+### `spfn contract`
+
+Manages the route contract — what a **separately deployed** client (a mobile app, an external
+API consumer) is promised. A web client needs none of this: it derives its types from
+`AppRouter` in the same build, so a broken response already fails the compile.
+
+Requires the `@spfn/core:contract` generator in `.spfnrc.ts`. Every command regenerates the
+contract from the router first, so a stale `contracts/current.json` is never what gets checked
+or released.
+
+```bash
+# Regenerate and compare against the newest released snapshot
+spfn contract check
+
+# Cut a release — writes contracts/released/1.3.0.json. Commit it.
+spfn contract release 1.3.0
+
+# List released snapshots
+spfn contract list
+```
+
+| Subcommand | Description | Exit code |
+|------------|-------------|-----------|
+| `contract check` | Compares the current contract against the newest released snapshot | 1 when a promise is broken |
+| `contract release <version>` | Writes the snapshot every later build is compared against | 1 when the contract is broken, the version already exists, or it is not newer than the newest one |
+| `contract list` (`ls`) | Lists released snapshots | 0 |
+
+`--dir <path>` overrides the contracts directory; by default it comes from the generator's
+`outputDir` in `.spfnrc.ts`.
+
+**`spfn build` runs the same gate.** A broken contract fails the build with a non-zero exit
+code — that is the point of hanging the check off codegen rather than leaving it to a
+separate step.
+
+See [`@spfn/core` contract docs](../core/src/contract/README.md) for the case table and the
+removal rules.
+
 ### `spfn db`
 
 Wraps Drizzle Kit with auto-generated config. Most commands read `DATABASE_URL` from the
@@ -186,6 +246,7 @@ loaded `.env` chain.
 | `db generate` (`g`) | Generate migrations from schema changes (timestamp-prefixed) |
 | `db push` | Diff with Drizzle Kit's current PostgreSQL engine and apply the selected DDL atomically. Destructive changes need confirmation; `--force` applies them, `--dry-run` previews |
 | `db migrate` (`m`) | Run pending migrations. `--with-backup` snapshots first |
+| `db status` | Show which migrations are applied and which are pending, for the project and for each installed function package |
 | `db studio` | Open Drizzle Studio. `-p, --port` (auto-finds a free port) |
 | `db check` | Verify the database connection |
 | `db drop` | Drop all tables — **destructive**, double-prompts (see [Pitfalls](#pitfalls)) |
@@ -396,7 +457,16 @@ the SPFN API with cookie forwarding and interceptors, resolving routes via the g
 
 ## Deployment
 
-`spfn build` then `spfn start`, or use the generated Docker files.
+Two targets, both shipping from the same repository.
+
+**Vercel — serverless, one origin, no container.** Run `spfn add vercel` (above) and
+deploy. Frontend and backend share a single Vercel origin. One caveat: the in-process job
+worker does not run there, so enqueuing works but nothing drains the queue — schedule a
+route that processes a batch (Vercel Cron), or run jobs on an always-on target.
+
+**Always-on — a long-lived process.** `spfn build` then `spfn start`, or the generated
+Docker files. Background jobs, WebSocket events and the periodic database health check all
+need this path.
 
 ```bash
 # Build + run locally
@@ -423,6 +493,42 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 
 ---
 
+## FAQ
+
+**`create` or `init` — which one?**
+`create` starts a new project: it runs `create-next-app` with SPFN's flags and then runs
+`init` inside it. `init` adds SPFN to a Next.js app that already exists. If you built
+something with an AI coding agent and now want a real backend under it, `init` is the one.
+
+**`bare` or `full`?**
+`full` is the recommended baseline: core, auth, i18n and MCP wired together, so you get a
+working authenticated app on day one. `bare` is core only — the architecture with nothing
+else decided. Automation should always pass `--mode` explicitly, because a `--yes` run
+without one still produces `bare` for backward compatibility.
+
+**Why doesn't my server restart when I edit a file?**
+Because hot reload is off by default. `spfn dev --watch` restarts the server on `src/server`
+changes. Next.js reloads on its own either way.
+
+**Do I have to use Docker?**
+No. Vercel is a first-class target and needs no container. Docker is the always-on path,
+and `docker compose up -d` is also the convenient way to get PostgreSQL and Redis locally —
+pointing at your own PostgreSQL works too. PostgreSQL itself is not optional.
+
+**Which Node version do I need?**
+18.18 or later for bare mode, 20 or later for full mode, because full mode includes the
+MCP server.
+
+**When do I have to run codegen by hand?**
+Whenever routes change outside `spfn dev`, which runs a codegen watcher for you. A stale or
+missing `src/generated/route-map.ts` makes the RPC proxy answer 404 — run `spfn codegen run`
+and commit the result.
+
+**Where do secrets go?**
+`.env.server` (gitignored, server-only) for backend values, `.env.local` for the session
+cookie secret that the Next.js runtime itself needs. Never `spfn.config.js` — that file is
+committed.
+
 ## Pitfalls
 
 - **`.env.server` is gitignored and server-only.** Put backend-only DB/secret values there,
@@ -441,7 +547,8 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
   destructive ones unless `--force`/confirmed. Prefer `db generate` + `db migrate` for
   production; `db push` is dev-only.
 - **`spfn add` requires a scoped package name** (must contain `/`) and only applies
-  migrations when `DATABASE_URL` is set — otherwise it skips with a hint.
+  migrations when `DATABASE_URL` is set — otherwise it skips with a hint. The single
+  exception is `spfn add vercel`, a built-in target rather than a package.
 - **Package manager is auto-detected from lockfiles.** If detection is wrong (e.g. mixed
   lockfiles), pass `--pm` to `create`. In a pnpm workspace, `create` installs from the
   workspace root, not the new project dir.
@@ -456,5 +563,7 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 
 ## Related
 
-- `@spfn/core` — server, route DSL, codegen, db, client runtime.
+- [`@spfn/core`](../core/README.md) — server, route DSL, codegen, db, client runtime.
+- [`@spfn/auth`](../auth/README.md) — what `--mode full` wires in for accounts and roles.
+- [`@spfn/mcp`](../mcp/README.md) — what `--mode full` wires in for operating the app.
 - Project root README — framework overview and getting started.