spfn 0.3.0-beta.5 → 0.3.0-beta.7

package/README.md

@@ -55,7 +55,7 @@ with `--pm`. In a pnpm workspace, `create` installs from the workspace root.
 
 Registered top-level commands: `create`, `init`, `add`, `dev`, `build`, `start`,
 `provision`, `codegen`, `contract`, `key`, `setup`, `db`, `env`, `ops`, `secret`,
-`cloud`.
+`cloud`, `kit`.
 
 ### `spfn create <name>`
 
@@ -118,7 +118,14 @@ its backend as Vercel Functions:
 |------|------------|
 | `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 |
+| `.npmrc` | which registry the `@spfn` scope resolves to — a mapping, not a credential |
+
+The registry token does **not** go in that `.npmrc`. pnpm 10 and later refuse to expand an
+environment variable in a registry credential that came from a project `.npmrc` — the file is
+committed, and a hostile edit could redirect the secret to a registry nobody chose. pnpm drops
+the line with a warning and the install fails as unauthorized. So the credential goes in Vercel's
+`NPM_RC` environment variable, which Vercel writes to the build container's user-level `~/.npmrc`,
+where pnpm still expands it. `spfn add vercel` prints the exact block to paste.
 
 Existing files are never overwritten; they are reported and skipped. The runtime behind
 the adapter is `createServerlessApp()` from `@spfn/core/server`. Afterwards, point
@@ -138,9 +145,15 @@ no pre-build needed.
 | `-p, --port <port>` | SPFN server port (sets `SPFN_PORT`) | `spfn.config.js` `ports.server`, then `8790` |
 | `-H, --host <host>` | SPFN server host (sets `SPFN_HOST`) | `spfn.config.js` `host`, then `localhost` |
 | `--allow-pending-migrations` | Start even when migrations are pending (they are listed as a warning) | off |
+| `--no-agent-files` | Do not write the SPFN instruction block into `AGENTS.md` (same as `SPFN_AGENT_FILES=0`) | writes on |
 
 Note: hot reload is **off by default** — pass `--watch` to restart on file changes.
 
+On startup `spfn dev` refreshes a marked block of SPFN conventions in the project's
+`AGENTS.md` (creating the file, and a `CLAUDE.md` that references it, when absent) so
+coding agents read the right idioms. Only the marked region is rewritten, and only when
+its content actually changed.
+
 Pending migrations stop the boot — see [Database](#spfn-db) for what the refusal looks
 like and how to override it.
 
@@ -263,7 +276,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 status` | Show which migrations are applied and which are pending, for the project and for each installed function package. `--json` prints one machine-readable report instead |
 | `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)) |
@@ -508,6 +521,162 @@ Because the package is the app's, it is resolved **from the directory the comman
 Run `spfn ops token` from the app's root; running it elsewhere reports the package as
 missing, and the message names the directory it looked in.
 
+### `spfn kit`
+
+Install, verify and update a **Superfunction Kit** — a licensed product that ships as a
+signed release: an SPFN scaffold, an exact dependency graph, files the Kit manages on the
+customer's behalf, and its own tooling. `spfn kit` is the generic installer for all of
+them. It hard-codes no product: which Kit, which packages and which files are managed all
+come from the signed setup descriptor and release manifest, and every judgement specific to
+a product comes from that product's own `/tooling` entry, which the CLI *discovers* among
+the packages the manifest installs.
+
+There is one binary and one command group. No Kit gets its own CLI.
+
+| Subcommand | Description |
+|------------|-------------|
+| `kit install <setup-url> <dir>` | Install the newest entitled stable release into a new or empty directory: verify the setup link, activate the license, create the SPFN base, materialize the managed files, install the exact graph, run migrations, run the gates, write the lock and make the first commit |
+| `kit restore` | Reinstall the exact release a clean clone records, using the committed lock and this machine's credential. Rewrites no source file |
+| `kit status` | Read-only report: installed release, activation, credential, managed drift, migrations, open operation. Anything the CLI could not determine is reported as `unknown` |
+| `kit check` | Read-only contract check with stable diagnostic codes, the path each is about, and the command that would fix it |
+| `kit plan [--to <release>]` | What an update would change, with the approval digest. Writes nothing |
+| `kit update [--to <release>] [--approve-plan <digest>]` | Update through the signed update edges, then gates, lock and commit |
+| `kit resume [operation-id]` | Continue an operation that stopped — after re-reading the project and confirming the recorded checkpoints still hold |
+| `kit abandon [operation-id]` | Record that an operation will not be finished, and report what it left behind. Deletes and rolls back nothing |
+
+**Secrets never travel as arguments.** There is no `--license-key <value>` option, by
+design: a secret on a command line is in the process table, the shell history and every log
+that records an argv. A key arrives either through a masked prompt or through
+`--license-key-stdin`. Once activation succeeds the key is discarded and only the local
+credential the server issued remains, in the OS keychain under its own service
+(`superfunction.spfn.kit`), separate from the env secrets `spfn secret` manages. The
+short-lived registry session is handed to the package-manager child process in its
+environment and nowhere else, as npm configuration addressed to the registry it opens
+(`npm_config_//host/npm/:_authToken`). The committed `.npmrc` maps the release's scopes to
+that registry and carries no credential at all — not a value, and not a variable naming
+one: pnpm 10 and later ignore a credential that reaches them from a project `.npmrc`, because that
+file is committed and a hostile edit could send the secret to another registry.
+
+**`--json` is the agent surface.** Every subcommand takes it, prints newline-delimited
+events with a stable `code`, `phase` and safe next command, and never opens a prompt. A
+JSON-mode command that needs a secret exits `2` and reports `input: masked-stdin`.
+
+| Exit | Meaning |
+|-----:|---------|
+| `0` | Completed, or an idempotent no-op |
+| `2` | Waiting for a person: a secret on stdin, or an exact plan approval |
+| `3` | Recoverable failure — `spfn kit resume` can continue it |
+| `4` | Refused before any write: drift, compatibility, entitlement or a busy project |
+| `5` | An external service could not be reached |
+| `10` | This CLI and the release speak different protocol versions |
+
+**What an install does not do.** It stops at a verified local repository: no cloud account
+is linked, nothing is pushed, nothing is deployed. That is a checkpoint for the agent to
+continue from, not a finished product install.
+
+**Approval is exact.** A breaking release or an external effect requires the digest of the
+very plan being run (`--approve-plan`), which can only be obtained by reading the plan.
+There is no blanket `--yes`.
+
+**One operation at a time.** A project holds a filesystem lock while a write operation
+runs. A lock left behind by a dead process is not simply deleted — it is reconciled against
+the operation journal, and reclaimed only when that journal agrees the work is over or the
+caller is resuming exactly the operation it belongs to.
+
+Generated state lives under `.spfn/`: `license.json` and `kit-lock.json` are committed and
+hold public identifiers only; `operations/` is per-machine and gitignored.
+
+**Exactness is proved, not assumed.** Before the package manager runs, every package the
+signed manifest names is fetched through the licensed registry proxy and checked twice: the
+version's integrity against the digest the manifest pinned, then the bytes that actually
+arrived against that same digest. The first says the registry agrees with the release; only
+the second says the file on this disk is the file the release described. The project's base
+arrives the same way — one scaffold archive, verified against the manifest's integrity
+before a single file is expanded, and refused outright if it names a path that would leave
+the project directory or overwrite a file that is already there.
+
+**An artifact is written as what it is.** A managed bridge is a file, and its
+bytes are the file. The scaffold and the Agent Pack are archives, and the CLI expands them —
+the pack into `.spfn/agent-pack/`, because a release's guides, schemas and checklists are a
+directory and belong to the release rather than among customer source. Both are proven
+against the manifest's digest before they are opened, and both refuse an entry that is a
+symlink or that would be written outside the project. What the pack expanded to is recorded
+in `.spfn/agent-pack.json` so drift can compare the tree file by file.
+
+**A materialize that stopped can be resumed.** Coming back to a half-written tree compares
+rather than overwrites: a file already holding exactly the bytes the release would write
+counts as done and the resume continues past it, and a file holding anything else is refused
+with that file left exactly as it was found. An update is the one operation that replaces —
+and only after drift has already been refused, so every managed file is known to hold the
+previous release's bytes rather than somebody's edit.
+
+**Release files are paid content, and are fetched as such.** Managed files, agent packs and
+the scaffold archive go out with the same bearer the private registry takes, and a refusal
+comes back in the same vocabulary — so "this machine's credential has been replaced" never
+arrives disguised as "that file is missing". The setup descriptor, the release catalog and
+the manifests stay public and carry no bearer: they are locators and promises about a
+release, and nothing anyone paid for is inside them.
+
+**Credentials rotate before they expire, not after.** A local credential opens the registry
+for a limited window. When that window is close to closing, the CLI asks the control plane
+for a replacement and writes it to the keychain *before* using it — a rotation that was not
+recorded can never have happened. A credential another machine has already replaced is
+reported as stale rather than as missing: the two mean different things, and only one of
+them means someone else's machine changed.
+
+**Nothing secret is ever an argument.** That now includes the keychain write itself: the
+`security` command goes in on stdin and the value goes in hex-encoded, so a local `ps` sees
+`security -i` and nothing else. It also means a keychain item can hold a value a quoted
+command line could not have carried at all, such as a multi-line key.
+
+**Machine-local state stays local.** `spfn kit` writes `.spfn/.gitignore` covering
+`operations/` the moment it creates that directory — in its own directory, never in the
+project's root `.gitignore`, which belongs to the customer. Without it a release whose
+scaffold forgot the rule would commit an operation journal and a lock naming the machine's
+hostname and process id.
+
+All ten places `spfn kit` touches the outside world are real implementations now. Six reach
+the network or a release artifact — signed catalogs and manifests, licence activation,
+credential rotation, the registry proxy, release artifacts and the scaffold — and four run
+something on this machine: `pnpm install --frozen-lockfile`, the migrations through
+`spfn db status --json` and `spfn db migrate`, the release's gates as the project's own
+scripts, and Git for `init`, `status` and the first commit. Nothing else: no remote is
+added and nothing is pushed.
+
+What still stops a real install is the trust root. The list of keys this CLI will accept a
+signed release from is **empty in this build**, because the release signing key is not
+published yet — so every signed document fails verification with `KIT_MANIFEST_INVALID`,
+which is the correct behaviour for a CLI that cannot yet tell a real release from a forged
+one. `SPFN_KIT_TRUSTED_KEYS` supplies a list for a staging run or a release rehearsal, as a
+JSON array of `{ "keyId", "publicKey" }` with base64 SPKI keys. It *replaces* the built-in
+list rather than adding to it.
+
+`SPFN_KIT_SETUP_ALLOWLIST` names the origins a setup link may be fetched from, as a
+comma-separated list of bare origins. It follows the same rule as the key list — it
+*replaces* the shipped one, so it can only ever narrow what this CLI will fetch a descriptor
+from — and it is the one place plain `http` is accepted, for `localhost` and `127.0.0.1`
+only, matched literally so a name like `127.0.0.1.example.test` is not one of them. A path,
+a query, a fragment, userinfo, or a non-loopback `http` entry makes the whole variable
+invalid rather than being quietly trimmed. A setup link may carry an explicit port, which is
+what lets a certification environment serve one; the link itself must still be `https`
+unless its origin is loopback *and* on the list.
+
+`SPFN_KIT_CONTROL_PLANE_URL` and `SPFN_KIT_REGISTRY_URL` point a project that has *not yet
+been activated* at a staging or local control plane. They are ignored once it has: the
+addresses a checkout recorded when it was licensed are the addresses it keeps, so a stray
+shell variable cannot move an activated project onto another service.
+
+`status` and `check` never depend on any of it: an unreachable remote must not hide local
+state, so they read the lock, the license file, the drift and the open operation from disk
+and report everything else as `unknown`.
+
+The command surface, journal, lock, keychain, verification and the whole install →
+activation → exact frozen install → restore path are exercised in `test/kit/`: the remote
+half against a loopback HTTP fixture answering with the licence service's and the registry
+proxy's own statuses and error bodies, the scaffold against real archives on real temporary
+directories, and one integration case that runs the whole install with pnpm resolving from
+a registry on 127.0.0.1, the gate as a real child process and a real Git commit at the end.
+
 ---
 
 ## Scaffold structure