spfn 0.3.0-beta.3 → 0.3.0-beta.5

package/README.md

@@ -2,7 +2,7 @@
 
 `spfn` takes a Next.js idea from prototype to production with a consistent full-stack
 architecture. It can scaffold either a core-only backend or a production baseline with
-authentication, internationalization, and an agent-facing MCP endpoint, then runs the
+authentication, internationalization, and a terminal operations surface, 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
@@ -31,7 +31,7 @@ is not supported — see [the root README](../../README.md#what-do-i-need-instal
 ## Usage
 
 ```bash
-# Prototype-to-Production baseline: core + auth + i18n + MCP
+# Prototype-to-Production baseline: core + auth + i18n + ops
 npx spfn@beta create my-app --mode full
 cd my-app
 docker compose up -d            # Postgres + Redis
@@ -54,7 +54,8 @@ with `--pm`. In a pnpm workspace, `create` installs from the workspace root.
 ## Commands
 
 Registered top-level commands: `create`, `init`, `add`, `dev`, `build`, `start`,
-`provision`, `codegen`, `contract`, `key`, `setup`, `db`, `env`, `ops`, `secret`.
+`provision`, `codegen`, `contract`, `key`, `setup`, `db`, `env`, `ops`, `secret`,
+`cloud`.
 
 ### `spfn create <name>`
 
@@ -71,7 +72,7 @@ pass `--mode full`.
 |--------|-------------|
 | `--pm <manager>` | Force package manager: `npm` \| `pnpm` \| `yarn` \| `bun` |
 | `--shadcn` | Also run `shadcn init` |
-| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, MCP) |
+| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, ops) |
 | `--skip-install` | Skip dependency install |
 | `--skip-git` | Skip `git init` |
 | `-y, --yes` | Skip prompts, use defaults |
@@ -86,7 +87,7 @@ already exists). See [Scaffold structure](#scaffold-structure) for what lands on
 
 | Option | Description |
 |--------|-------------|
-| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, MCP) |
+| `--mode <mode>` | `bare` (core only) \| `full` (core, auth, i18n, ops) |
 | `-y, --yes` | Skip prompts, use defaults |
 
 Generated projects pin `drizzle-orm` and `drizzle-kit` to `1.0.0-rc.4`, matching
@@ -384,6 +385,31 @@ Schema-driven: a secret declared with `envSecret({ generate: 'base64url32' })` c
 minted/rotated automatically (`secret generate`/`rotate`); one without `generate` is an
 external value you paste in (`secret set`).
 
+### `spfn cloud`
+
+Free-tier management for apps deployed to your own **Vercel Hobby + Supabase Free**
+accounts: see the plan limits, watch live usage against them, keep the Supabase
+project from pausing, and sync env vars/API keys. Account tokens and key values live
+in the OS keychain and never appear in command output.
+
+| Subcommand | Description |
+|------------|-------------|
+| `cloud link` | Connect accounts: Vercel access token + Supabase personal access token (masked prompt or `VERCEL_TOKEN`/`SUPABASE_ACCESS_TOKEN` env), pick the project on each side. Identifiers land in gitignored `.spfn/cloud.json`; tokens go to the keychain |
+| `cloud limits` | The free-plan limits (constants verified against the official docs, date shown) — works before `link` |
+| `cloud usage` | Current usage: Vercel billing feed (rolling 30 days), Supabase DB size + last-24h API requests |
+| `cloud status` | Usage measured against the limits on one screen; items at ≥80% get a migration warning |
+| `cloud keepalive` | Daily cron hitting `/api/backend/_core/health?detailed=true` (the detailed check runs a DB query, which is what prevents the ~7-idle-day pause). Vercel cron by default; `--github-actions --url <deployed-url>` for a workflow instead |
+| `cloud env pull` | Supabase keys → local: project URL + anon key into `.env.local`, service-role key into the keychain (`.env.server` gets a reference). `--db-url` also composes `DATABASE_URL` (prompts for the DB password) |
+| `cloud env push KEY…` | Push local env values to the Vercel project env by name. Values resolve from `.env`/`.env.local`/`.env.server`+keychain; everything is sent encrypted except `NEXT_PUBLIC_*` |
+
+Free-tier behavior worth knowing (also printed by `cloud limits`): Vercel Hobby
+allows one cron at most once per day and pauses a capability when its rolling
+30-day limit is hit (it never bills); Supabase Free quota is summed per
+organization (except DB size), and org totals like egress/MAU have no public API —
+`cloud status` shows per-item numbers and points at the dashboard for the rest.
+Hobby is limited to personal, non-commercial use — a monetized app needs Vercel Pro
+or a migration off the free tier.
+
 ### `spfn setup icons`
 
 Install and configure SVGR for SVG-as-component imports (Next.js only).
@@ -418,6 +444,29 @@ listSignups  GET /_ops/signups
 Add `--json` for the raw JSON Schema. The server still validates every call — `--describe`
 reports what it will accept, and the app's answer decides.
 
+#### Capability modules
+
+An app can also mount ops commands a package described, with
+[`defineOpsModule`](../core/README.md#can-a-package-ship-ops-commands). Those commands are
+named `<module>.<command>` and carry a summary, an effect and their scopes, so the CLI can
+group them and say what each one does. From **0.3.0-beta.5**:
+
+```bash
+spfn ops modules                                      # what is mounted, and from where
+spfn ops modules --json                               # same, machine-readable
+spfn ops list --module ledger                         # just that module's commands
+spfn ops call ledger.compact --yes                    # effect=destructive needs this
+```
+
+`spfn ops call` refuses a command the app declared `effect: destructive` unless `--yes` is
+given. It refuses the same way when the app announced module metadata this CLI could not
+validate: the effect is then unknown rather than absent, and an unknown effect is not
+treated as a safe one. The command still lists — an operator reading a short list would
+otherwise take it for the app's whole surface — and the warning names what was dropped.
+
+Everything in the manifest is the app's own text written to your terminal, so control
+characters in it are replaced before anything is printed.
+
 The app URL comes from `--app` or `SPFN_OPS_APP`, and it must be **https** — every one of
 these commands carries a secret, and `token issue` carries an administrator's password.
 `http` is accepted only against `localhost`, `127.0.0.1` and `::1`, where there is no
@@ -498,24 +547,30 @@ src/
   app/auth/callback/page.tsx         # OAuth session handoff
   i18n/catalogs.ts                   # application-owned en/ko starter messages
   i18n/server.ts                     # configured server-side i18n registry
-  server/mcp.ts                      # authenticated /mcp endpoint + starter app_status tool
-  server/router.ts                   # authRouter + mcpRouter + global authenticate
+  server/routes/ops.ts               # ops routes under /_ops + the manifest `spfn ops` reads
+  server/router.ts                   # authRouter + opsRouter + global authenticate
   server/server.config.ts            # createAuthLifecycle + i18n startup
 next.config.ts                       # /_auth/* callback rewrite
 .env.local                           # generated auth session secret (gitignored)
-.env.server                          # auth keyring + MCP operator key (gitignored)
+.env.server                          # auth keyring (gitignored)
 ```
 
 The full RPC proxy imports the auth interceptor and merges `authRouteMap`. Internal auth
-and MCP keys are generated with cryptographic randomness in ignored local env files;
+keys are generated with cryptographic randomness in ignored local env files;
 `.env.example` contains placeholders only. Add only the provider keys you use, then run
-`pnpm spfn db migrate`. The starter MCP endpoint accepts `SPFN_MCP_API_KEY` as a Bearer
-token for first-party operation; replace that validator with OAuth before third-party access.
+`pnpm spfn db migrate`.
+
+Operating the app is [`spfn ops`](#spfn-ops), not a dashboard: the starter
+`src/server/routes/ops.ts` exposes two read commands, and `spfn ops` discovers them from
+the running server's manifest. Issuing the first token signs in as an administrator, so
+uncomment `SPFN_AUTH_ADMIN_ACCOUNTS` in `.env.server` and restart before
+`spfn ops token issue`. The ops surface adds no dependency — the router comes from
+`@spfn/core/ops` and the tokens from `@spfn/auth`.
 
 `init` also patches `package.json` (scripts: `spfn:dev`, `spfn:server`, `spfn:next`,
 `spfn:build`, `spfn:start`, `codegen`; deps: `@spfn/core`, `spfn`, `drizzle-orm`,
 `@sinclair/typebox`, `concurrently`, etc.; full also adds `@spfn/auth`, `@spfn/i18n`,
-`@spfn/mcp`, auth's `@spfn/notification` peer, and a Node `>=20.0.0` engine when the
+auth's `@spfn/notification` peer, and a Node `>=20.0.0` engine when the
 existing range still permits older Node versions), excludes `src/server` from the root
 `tsconfig.json` (Vercel compat), and adds `.spfn/`, `.env.local`, `.env.server` to
 `.gitignore`.
@@ -621,8 +676,8 @@ type ships from `spfn` (`@type {import('spfn').SpfnConfig}`).
 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
+`full` is the recommended baseline: core, auth, i18n and the ops surface wired together, so
+you get a working authenticated app on day one, operable from the terminal. `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.
 
@@ -637,7 +692,7 @@ pointing at your own PostgreSQL works too. PostgreSQL itself is not optional.
 
 **Which Node version do I need?**
 20 or later, in both modes. `@spfn/core` runs on `@hono/node-server` 2, which declares
-that floor, and full mode's MCP server needs the same.
+that floor, and full mode's `@spfn/auth` needs the same.
 
 **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
@@ -685,5 +740,6 @@ committed.
 
 - [`@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.
+- [`@spfn/mcp`](../mcp/README.md) — an agent-facing MCP endpoint, added on demand with
+  `spfn add @spfn/mcp`.
 - Project root README — framework overview and getting started.