spfn 0.3.0-beta.4 → 0.3.0-beta.5

package/README.md

@@ -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>`
 
@@ -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