create-feltkit 0.3.0 → 0.3.2

package/template-managed/README.md

@@ -0,0 +1,222 @@
+# Inventory on Managed FeltDB: a FeltKit example
+
+A small inventory service: items with stock levels, and a movement recorded with every stock
+change in the same FeltDB transaction. Its state lives in **Managed FeltDB**, the hosted FeltDB
+service. Nothing on the app's host holds state, so you can restart or redeploy the app and
+nothing is lost.
+
+```bash
+npm create feltkit@latest inventory -- --template managed
+```
+
+## How this differs from the default starter
+
+| | Default starter (`--template tasks`) | This starter (`--template managed`) |
+|---|---|---|
+| Where state lives | local FeltDB: `.feltkit/<env>/state`, or a FeltDB server you run (`FELTDB_URL` + `FELTDB_TOKEN`) | Managed FeltDB: one managed *application*, one *environment* (`production` by default) |
+| Development and tests | local FeltDB | local FeltDB, the same (`npm test`, `npm run dev`) |
+| What FeltDB stores | any collection | only what the promoted **contract** declares: `feltdb.contract.json`, generated by `feltkit contract` and checked in |
+| AppPort Services (files, intelligence, …) | yes | no: their collections can't be declared in a contract yet, so `feltkit contract` refuses an app that enables them |
+| Credentials | none for local state | a **runtime key** with four scopes (server-side only) and a **control key** for publishing contracts (never in the running app), both minted by the FeltDB CLI |
+| Deployment | `feltkit deploy` (a Docker artifact with a state volume) | `Dockerfile`, `docker-compose.yml`, `fly.toml`: stateless, configured by the environment |
+
+Managed FeltDB is an external service. Nothing here provisions or operates it: `feltdb
+init-managed` creates *your application* in it, using your FeltDB account.
+
+## What's here
+
+| Path | What it is |
+|---|---|
+| `feltkit/app.ts` | roles (`clerk`, `auditor`), collections `items` and `movements` |
+| `feltkit/items.ts` | `list`, `get`, `create` and `adjust` (AppPort capabilities `items.create` and `stock.adjust`), `history` |
+| `feltkit/system.ts` | `system:status`: an authenticated read through the configured backend; names the backend, never a key |
+| `feltdb.contract.json` | the FeltDB application contract: your collections, FeltKit's records, FeltDB's agent state |
+| `scripts/managed-env.mjs` | runs FeltKit with the runtime settings only; refuses missing or contradictory ones |
+| `Dockerfile`, `.dockerignore`, `docker-compose.yml` | the image, and a way to run it locally against Managed FeltDB |
+| `fly.toml`, `scripts/deploy-fly.mjs` | deployment to Fly.io |
+| `tests/` | `inventory` (persistence and refusals, local), `config` (configuration contract, deploy script), `managed.live` (against Managed FeltDB) |
+
+## Prerequisites
+
+- Node.js 20.11 or later, and npm.
+- A FeltDB account (`npm run managed:setup` creates one if the e-mail is new). The account
+  creates the application and its keys, so you need permission to manage keys for it. The
+  account service never issues a scope you don't hold.
+- To deploy: Docker, or [flyctl](https://fly.io/docs/flyctl/install/) signed in to Fly.io.
+
+## 1. Run it locally
+
+```bash
+npm install
+npm test          # local FeltDB per test: persistence, refusals, roles, configuration
+npm run dev       # http://localhost:3000, state in .feltkit/development/state
+```
+
+Development and tests always use local FeltDB, so you don't need an account for either.
+
+## 2. Set up Managed FeltDB: account, application, keys, contract
+
+```bash
+npm run managed:setup
+```
+
+This runs `feltkit contract` (writes `feltdb.contract.json`), then FeltDB's own CLI (shipped with
+`@feltdb/core`):
+
+```bash
+feltdb init-managed --contract feltdb.contract.json --runtime-scopes minimal
+```
+
+It signs you in (or signs you up), prompting for your e-mail and password. For CI, set
+`FELTDB_MANAGED_EMAIL` and `FELTDB_MANAGED_PASSWORD` instead. It then:
+
+1. creates or reuses the managed application named after `package.json`'s `name` (`--name` to choose);
+2. mints a **control key** (publish and promote contracts) and a **runtime key** with
+   `application:read`, `application:revision:read`, `state:read` and `state:write`, nothing more;
+3. writes `.env.local` (mode 600) and `.feltdb/managed.json`; both are in `.gitignore`;
+4. publishes and promotes the contract to `production`, and checks that the runtime key resolves it.
+
+| Variable (`.env.local`) | Secret? | Used by |
+|---|---|---|
+| `FELTDB_URL` | no | the app |
+| `FELTDB_APPLICATION_ID` | no | the app |
+| `FELTDB_ENVIRONMENT` | no | the app (it is also FeltKit's environment) |
+| `FELTDB_TOKEN` | **yes**: the runtime key | the app |
+| `FELTDB_MANAGED_CONTROL_API_KEY` | **yes**: the control key | `feltdb publish` only; never the app |
+
+`init-managed` also writes `FELTDB_NAMESPACE`, `FELTDB_MODE` and `VITE_FELTDB_*`, which hold no
+secrets. The app doesn't use them, and `scripts/managed-env.mjs` doesn't pass them on.
+
+## 3. Run it against Managed FeltDB from your machine
+
+```bash
+npm run managed:session -- --id ops --role clerk      # prints a session token once
+npm run managed:start                                 # http://localhost:3000, state in Managed FeltDB
+```
+
+Both go through `scripts/managed-env.mjs`, which reads `.env.local`. It passes FeltKit only the
+four runtime settings and refuses to start if one is missing. `managed:start` prints
+`State  remote https://…`.
+
+Production has no development sign-in, so callers use a session (`Authorization: Bearer <token>`)
+or your own `auth.authenticate` hook in `feltkit/app.ts`. Create sessions while the server is
+stopped (or from another machine). A running production server's admin API answers only verified
+operators.
+
+## 4. Verify reads and writes
+
+```bash
+TOKEN=fks_…   # from managed:session
+curl -s -X POST localhost:3000/api/mutation/items:create -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"args":{"sku":"BOLT-10","name":"M10 bolt","quantity":100}}'
+curl -s -X POST localhost:3000/api/mutation/items:adjust -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"args":{"sku":"BOLT-10","delta":-30,"reason":"order 1"}}'
+curl -s -X POST localhost:3000/api/query/items:list     -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'
+curl -s -X POST localhost:3000/api/query/system:status  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'
+# → {"ok":true,"value":{"environment":"production","storage":{"kind":"remote","location":"https://api.feltdb.com","durable":true},"readable":true,…}}
+curl -s localhost:3000/_feltkit/health   # liveness: 200 once FeltKit reached FeltDB with its key at startup
+```
+
+## 5. Restart and check the state is still there
+
+Stop the app (Ctrl+C), run `npm run managed:start` again, and repeat `items:list`: the same items
+and quantities come back. Or run the automated check, which writes a `live-test-…` item, kills
+the app, starts a new process and reads it back:
+
+```bash
+FELTKIT_MANAGED_LIVE=1 npm run managed:test
+```
+
+## 6. Deploy
+
+The image holds no state and no keys. It is configured entirely by the environment at run
+time, so the same image runs anywhere.
+
+**Docker (any host).** Locally, with the settings from step 2:
+
+```bash
+docker compose --env-file .env.local up --build
+```
+
+The compose file passes the container only `FELTDB_URL`, `FELTDB_APPLICATION_ID`,
+`FELTDB_ENVIRONMENT` and `FELTDB_TOKEN`. On any other platform, set the first three as plain
+configuration and `FELTDB_TOKEN` from its secret store. Point health checks at
+`GET /_feltkit/health` on port 8080. The image checks that `feltdb.contract.json` matches the
+source at build time.
+
+**Fly.io.**
+
+```bash
+fly apps create <your-app-name>             # once
+npm run deploy:fly -- --app <your-app-name>
+```
+
+`scripts/deploy-fly.mjs` stages `FELTDB_TOKEN` as a Fly secret by piping it to
+`fly secrets import --stage` on stdin, so it never appears in a command line or output. It then
+runs `fly deploy` with the three non-secret settings. `fly.toml` holds the port, the health check
+and `FELTDB_ENVIRONMENT`.
+
+Then repeat steps 4 and 5 against the deployed URL. Create the session from your machine with
+`npm run managed:session`: sessions live in Managed FeltDB, so the deployed app accepts them.
+
+## Changing the data model
+
+1. Edit `feltkit/app.ts`.
+2. Run `npm run managed:publish`. This regenerates the contract and publishes it with
+   `feltdb publish --contract`. FeltDB classifies the change. A change it classifies as breaking,
+   migration-requiring or authorization-sensitive (adding a field is `MIGRATION_REQUIRED`) is
+   staged, but not activated until you rerun with `-- --approve-destructive-changes`. A refused or
+   unapproved publish leaves the active contract in place.
+3. Commit `feltdb.contract.json` with the code, then redeploy. The app that is already running needs
+   no restart. Its next request after the promotion is refused once (`CONFLICT`, `feltdbCode:
+   REVISION_NOT_ACTIVE`, nothing written, not resent), and every request after that runs under the
+   new contract. A compatible change, such as a new optional field, keeps the old code working. An
+   incompatible one refuses the old code's writes until the new code is deployed: FeltDB never
+   stores them under the old contract.
+
+## Keys: rotate, narrow, revoke
+
+```bash
+npx feltdb managed keys list                                        # ids, names, scopes; never secrets
+npx feltdb managed keys create --name inventory-runtime-2 --scopes minimal   # new FELTDB_TOKEN in .env.local
+npm run deploy:fly -- --app <your-app-name>                         # or update your platform's secret
+npx feltdb managed keys revoke inventory-runtime                    # the old key now gets AUTHENTICATION_REQUIRED
+```
+
+`--stdout` writes `FELTDB_TOKEN=…` to a pipe (for example into a secret manager) and is refused on a
+terminal. A key is bound to this application. Wildcard (`*`) keys are operator keys and are
+refused.
+
+## Troubleshooting
+
+| You see | Means | Do |
+|---|---|---|
+| `Managed FeltDB configuration is incomplete: FELTDB_… is not set` | the launcher found no value in the environment or `.env.local` | run `npm run managed:setup`, or set it on your platform |
+| startup fails with `AUTHENTICATION_REQUIRED` | the runtime key is wrong, revoked, or for another FeltDB | mint a new one (`feltdb managed keys create`) and update `FELTDB_TOKEN` |
+| `FORBIDDEN` | the key is for another application or lacks a scope | check `FELTDB_APPLICATION_ID`; mint with `--scopes minimal` |
+| `NOT_FOUND … application environment has no active contract` | nothing is promoted to `FELTDB_ENVIRONMENT` | `npm run managed:publish`, or fix `FELTDB_ENVIRONMENT` |
+| `UNKNOWN_COLLECTION` or `record contains an unknown field` | the contract is older than the code | `npm run managed:publish` (approve it) |
+| `CONFLICT` with `feltdbCode: REVISION_NOT_ACTIVE` | a contract was promoted since this process's last request; nothing was written, and FeltKit did not resend it | the request was built for the previous contract: if it still makes sense, send it again, and it runs under the new contract (once per promotion). Retrying it is the caller's decision, never automatic |
+| startup fails with `SERVICE_UNAVAILABLE` / names `FELTDB_URL` | FeltDB can't be reached | check `FELTDB_URL` and network egress. Managed FeltDB's `/health` and `/ready` are public |
+| `FELTDB_ENVIRONMENT is "…", but this is FeltKit's … environment` | the two disagree | FeltKit uses the FeltDB environment of its own name: set one of them |
+| `This application enables AppPort Services` from `feltkit contract` | services can't run on Managed FeltDB yet | remove `services`, or use local or self-hosted FeltDB |
+| `The production environment is already served by pid …` | a FeltKit server for this environment is running on this host | stop it first (or run the CLI on another machine) |
+
+## Clean up
+
+- Revoke keys you no longer use: `npx feltdb managed keys revoke <name-or-id>`.
+- `live-test-…` items written by `managed:test` stay in your application. They are ordinary
+  records, so remove them with your own mutation if you need to.
+- Delete the Fly app with `fly apps destroy <your-app-name>`. Local files: `.env.local`,
+  `.feltdb/`, `.feltkit/`.
+- The managed application itself is deleted from your FeltDB account. This repository has no
+  command that deletes it.
+
+## What's verified, and where
+
+- `npm test` (here): persistence, refusals, roles, the configuration contract, the Fly deploy
+  script with a stand-in `fly`.
+- `npm run test:managed` in the FeltKit repository: this example's full workflow, setup through
+  refusals, against a separately running, auth-on `feltdb-server` provisioned the way Managed
+  FeltDB is. It covers app and authority restarts, an idempotent retry across a restart, a
+  refused key, an unreachable authority, and no secret in any output.
+- `FELTKIT_MANAGED_LIVE=1 npm run managed:test`: the live service. It runs only with your
+  credentials.

package/template-managed/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.feltkit/
+# Written by `feltdb init-managed` / `feltdb managed keys`: keys and local deployment state. Never commit.
+.env
+.env.*
+.feltdb/

package/template-managed/docker-compose.yml

@@ -0,0 +1,17 @@
+# Run the image locally against Managed FeltDB, with the settings `npm run managed:setup` wrote:
+#
+#   docker compose --env-file .env.local up --build
+#
+# Compose reads .env.local only to fill in the variables below; the container receives these
+# four and nothing else (not the control key).
+services:
+  inventory:
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      FELTDB_URL: ${FELTDB_URL:?run npm run managed:setup or set FELTDB_URL}
+      FELTDB_APPLICATION_ID: ${FELTDB_APPLICATION_ID:?run npm run managed:setup or set FELTDB_APPLICATION_ID}
+      FELTDB_ENVIRONMENT: ${FELTDB_ENVIRONMENT:-production}
+      FELTDB_TOKEN: ${FELTDB_TOKEN:?run npm run managed:setup or set FELTDB_TOKEN}
+    restart: unless-stopped