@fabrika/app 0.3.3 → 0.4.1

package/skill/references/app-setup.md

@@ -0,0 +1,370 @@
+# references/app-setup.md — the repository of an application
+
+An application is the root of its own repository: Zerops reads `zerops.yaml` there. In the fabrika-platform
+repository an example is a workspace under `examples/<name>/`, laid out the same way. This file shows an application
+with tables and an SPA; a new one starts without either (`references/start.md`), and each part below that belongs to
+the SPA is added with it.
+
+## Packages and compiler
+
+```json package.json
+{
+	"name": "tasks",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build:manifest": "fabrika app build --env=prod",
+		"build:web": "bun build-web.ts",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test --isolate"
+	},
+	"dependencies": {
+		"@fabrika/app": "^0.4.1",
+		"@fabrika/db": "^0.4.1",
+		"@fabrika/provider-zerops": "^0.4.1",
+		"@fabrika/proxy-core": "^0.4.1",
+		"@fabrika/ui": "^0.4.1",
+		"@sentry/browser": "10.69.0",
+		"kysely": "0.29.6",
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"zod": "^3.25.76"
+	},
+	"devDependencies": {
+		"@fabrika/check": "^0.4.1",
+		"@fabrika/cli": "^0.4.1",
+		"@fabrika/platform": "^0.4.1",
+		"@happy-dom/global-registrator": "^20.11.2",
+		"@types/bun": "latest",
+		"@types/react": "^19.0.0",
+		"@types/react-dom": "^19.0.0",
+		"typescript": "^5.9.3"
+	}
+}
+```
+
+- The name is not under `@fabrika/*` (that scope is the platform's), and every `@fabrika/*` version is a registry
+  range, never `workspace:*`. The checker refuses both (`package-replacement`). Inside the fabrika-platform repository
+  Bun still links the workspace copies.
+- `build:web` builds the SPA: add it, `build-web.ts`, `web/`, the contract's `site` mount and the `bun run build:web`
+  line of `zerops.yaml` when the application gets an SPA, and not before.
+- `kysely` is there for the generated schema's types. `@sentry/browser` reports the SPA's errors to Operations, from
+  the DSN and release the framework serves at `<prefix>/__fabrika-config.json`. The same file carries
+  `public: { <VARIABLE>: <value> }`: each form challenge's `siteKey`, and the variables the SPA mount lists in
+  `c.spa(prefix, { …, public: ['SIGNUP_URL'] })`. A page reads a per-environment public value (a site key, a link
+  target) there, never as a build-time constant; it holds no other variable, and the contract refuses a secret in it.
+  `react`, `react-dom` and `@fabrika/ui` (with `@types/react`, `@types/react-dom` and `@happy-dom/global-registrator`
+  for the screen tests) are the SPA's: add them with it.
+- After you create a new workspace in a monorepo, run `bun install` at the repository root. Until then every
+  `@fabrika/*` import fails and tsc reports a cascade of implicit `any`s that are not your bugs.
+- To try unreleased packages outside the fabrika-platform repository, run `bun scripts/release.ts pack --local
+  --artifacts=<dir>` there. It writes the tarballs, `release-manifest.json` and `install.json`. Copy the tarballs into
+  the application's `vendor/`, replace every `@fabrika/*` entry of `dependencies` and `devDependencies` with the
+  `dependencies` of `install.json`, add its `overrides`, and run `bun install`. Then run the checker as
+  `fabrika-check --packed <dir>/release-manifest.json`: without the flag it refuses the tarballs. A deployed
+  application never takes this form; the platform build installs from the registry.
+- The local pack is the one way to run a platform checkout's packages in an application. Never `bun link` a
+  `@fabrika/*` package: a linked package resolves its dependencies and peers from the checkout, so the application
+  runs a second React (every hook fails), a second zod and a second kysely. Installed from `vendor/`, the packages
+  resolve `react`, `zod` and `kysely` from the application's own `node_modules`. The pack's version names the
+  checkout's commit: after a change in the platform, commit it, pack again, and replace the block with the new
+  `install.json`.
+
+```json tsconfig.json
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"jsx": "react-jsx",
+		"strict": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		"noPropertyAccessFromIndexSignature": true,
+		"forceConsistentCasingInFileNames": true,
+		"skipLibCheck": true,
+		"isolatedModules": true,
+		"noEmit": true,
+		"types": ["@types/bun"]
+	},
+	"include": ["src/**/*", "web/**/*", "dev/**/*", "*.ts"]
+}
+```
+
+The tsconfig stands alone: no `extends` of a file outside the application. `lib` is ES2022, so `toSorted` and other
+newer methods are not there.
+
+## The composition
+
+```ts src/app-kit.ts
+import { defineApp } from '@fabrika/app/contract'
+import { tables } from './db/tables'
+import { vocabulary } from './vocabulary'
+
+export const app = defineApp(vocabulary, tables)
+```
+
+```ts fabrika.contract.ts
+import { app } from './src/app-kit'
+import { comments } from './src/comments/endpoints'
+import { members } from './src/members/endpoints'
+import { priorities } from './src/priorities/endpoints'
+import { projects } from './src/projects/endpoints'
+import { reports } from './src/reports/endpoints'
+import { tasks } from './src/tasks/endpoints'
+
+export const contract = app.contract((c) => ({
+	api: c.rpc('/api', {
+		projects,
+		tasks,
+		comments,
+		reports,
+		members,
+		priorities,
+	}),
+	site: c.spa('/', { dir: 'dist/web', access: { member: true } }),
+	health: c.health('/healthz'),
+}))
+```
+
+```ts src/app.ts
+import { serve } from '@fabrika/app/implement'
+import { scoped } from '@fabrika/db'
+import { contract } from '../fabrika.contract'
+import { tables } from './db/tables'
+
+export default serve(contract, { database: scoped(tables) })
+```
+
+- Mounts: `c.rpc(prefix, groups)` once per prefix, `c.spa(prefix, { dir, access })`, `c.health('/healthz')` (required
+  on Zerops), `c.form(path, { input, appendTo, then? })` (an anonymous form that appends one row and runs no handler), a
+  webhook, a link mount. An SPA's `access` is `{ member: true }`, `{ action, over }`, or `{ public: true }` for a page
+  anyone opens without signing in (a landing page, a public form): the approver sees it as "for anyone". A public SPA
+  at `/` answers every `GET` no more specific endpoint serves; give a member SPA its own prefix (`/app`). Sections:
+  `files`, `jobs`, `exports`, `csp` (`connectSrc`, `imgSrc`, `frameAncestors`, `scriptSrc`, `frameSrc`, `styleSrc`,
+  `fontSrc`: exact `https://` origins, each with a `purpose`, at most 16 each). A hosted typeface needs both its
+  stylesheet origin in `styleSrc` and its font origin in `fontSrc`; font files under the SPA's `dir` need neither. No path under `/__fabrika`.
+- A public form's abuse control, all optional on `c.form`: `rate: { perClient, perForm }` (per minute, shared by
+  every instance; 10 and 100 by default; 429 past either), `honeypot: '<field>'` (a `z.optional(z.string())` input
+  field the page hides; a filled one gets the same answer and writes nothing) and
+  `challenge: { provider: 'turnstile', secret: 'TURNSTILE_SECRET', siteKey: 'TURNSTILE_SITE_KEY' }`. A challenge needs the input field
+  `challengeToken: z.string()`, which the page fills from the Turnstile widget rendered with `action` set to the
+  form's mount name; the framework verifies it on the server (a failed token 400, an unreachable provider 503, no
+  row either way) and adds Turnstile's origin to the CSP. `secret` names an application variable the human sets,
+  never the value; without it the application does not boot. `siteKey` names the variable with the widget's public
+  site key, which every SPA mount serves its pages (below). Neither field reaches the inbox, so neither is a
+  column. On Zerops every visitor still shares one client address (the balancer), so `perClient` acts as a second
+  per-form limit: raise it, and use the challenge. `references/public-intake.md` builds a whole public intake on it.
+- `then: '<job>'` on `c.form` names a cron job of the same contract (`jobs`), which each accepted submission kicks
+  once its row committed: a run starts within seconds, under the job's own key, and the answer stays the same constant
+  and never waits for it. Kicks coalesce on the job's lease (at most one run and one pending, however many visitors
+  submit), so the job still drains its inbox in batches under its own budgets. Keep its schedule: it is the recovery
+  path for a kicked run that died. A kick carries nothing; the job reads its inbox. `kit.runJob` first waits for the
+  kicked runs.
+- `src/app.ts` composes and does nothing else. A dependency built from the application's own variables is
+  `defineDeps(build)`, passed as `serve(contract, { database, deps })` and read in a handler with `get()`. Never read
+  `process.env`. `build` runs at every boot, the generated tests' too, which pass no variable: read a variable when
+  the dependency is used, and fail there (`src/mail.ts` in `references/public-intake.md`). A handler of an endpoint the
+  generated tests cover records an outbox row instead, and a job calls the dependency (`references/endpoint.md`).
+
+## The deploy surface (Zerops)
+
+```ts fabrika.config.ts
+import { compileContract, schemaFromContract } from '@fabrika/app/contract'
+import { defineApp, type ZeropsServiceSpec } from '@fabrika/provider-zerops'
+import { contractProxyTable } from '@fabrika/proxy-core/manifest'
+import { contract } from './fabrika.contract'
+import { tables } from './src/db/tables'
+
+const compiled = compileContract(contract, tables)
+
+const services = (): ZeropsServiceSpec[] => [
+	{
+		hostname: 'tasksdb',
+		type: 'postgresql:single@18',
+		profile: 'oltp-hobby',
+		priority: 100,
+	},
+	{
+		hostname: 'tasksapi',
+		type: 'alpine/bun@1.3',
+		priority: 10,
+		enableSubdomainAccess: false,
+		minContainers: 1,
+		maxContainers: 2,
+	},
+]
+
+export default defineApp({
+	id: contract.vocabulary.app,
+	schema: schemaFromContract(compiled),
+	target: {
+		platform: 'zerops',
+		services,
+		contract: compiled,
+		proxy: { upstream: 'tasksapi:3000', ...contractProxyTable(compiled) },
+		deployService: 'tasksapi',
+		zeropsSetup: 'tasksapi',
+	},
+})
+```
+
+```yaml
+# zerops.yaml: write only build.base, build.os and the SPA's buildCommands; the platform generates the rest.
+# Without an SPA, the build holds only base: the platform installs the packages itself.
+zerops:
+  - setup: tasksapi
+    build:
+      base: alpine/bun@1.3
+      buildCommands:
+        - bun install --frozen-lockfile
+        - bun run build:web
+```
+
+The platform's build runs the tests, writes the entrypoint, runs `fabrika-check` and the type check. Its start script
+runs `fabrika db migrate`, `fabrika db codegen --verify` and `fabrika db test-isolation` before the server: the
+application is not ready until every generated test passes. It writes every `FABRIKA_*` variable; never set one.
+
+## The SPA (added when the application has one)
+
+The SPA is React, built from the screens and hooks of the framework: `@fabrika/app/react` runs the typed client's
+calls, and `@fabrika/ui` holds the components. Build a screen from the kit; never write a DOM helper, a router or a
+component set of your own. `references/spa.md` shows every component, the forms, the routes and the tests.
+
+```html web/index.html
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta name="viewport" content="width=device-width, initial-scale=1">
+		<title>Tasks</title>
+		<script type="module" src="./start.tsx"></script>
+	</head>
+	<body>
+		<div id="root"></div>
+	</body>
+</html>
+```
+
+```ts web/api.ts
+import { createClient } from '@fabrika/app/client'
+import { contract } from '../fabrika.contract'
+
+export const api = createClient(contract, 'api', { bounceOnAuth: true })
+```
+
+```tsx web/mine.tsx
+import { useInfiniteQuery } from '@fabrika/app/react'
+import { type Column, DataTable, PageHeader, StatusPill } from '@fabrika/ui'
+import { api } from './api'
+
+type Task = {
+	readonly id: string
+	readonly title: string
+	readonly status: string
+}
+
+const columns: readonly Column<Task>[] = [
+	{ key: 'title', header: 'Task', grow: true, cell: (task) => task.title },
+	{
+		key: 'status',
+		header: 'Status',
+		cell: (task) => <StatusPill>{task.status}</StatusPill>,
+	},
+]
+
+export function MyTasks() {
+	const mine = useInfiniteQuery(api.tasks.mine, {})
+	return (
+		<>
+			<PageHeader title="My tasks" lead="Open tasks assigned to you." />
+			<DataTable
+				caption="My tasks"
+				columns={columns}
+				rows={mine.items}
+				rowKey={(task) => task.id}
+				status={mine.status === 'error'
+					? 'error'
+					: mine.status === 'success'
+					? 'ready'
+					: 'loading'}
+				error={mine.error?.message}
+				onRetry={() => void mine.retry()}
+				loadMore={{
+					hasMore: mine.hasMore,
+					loading: mine.loadingMore,
+					onLoadMore: () => void mine.loadMore(),
+				}}
+			/>
+		</>
+	)
+}
+```
+
+```tsx web/start.tsx
+import '@fabrika/ui/styles.css'
+import { FabrikaProvider } from '@fabrika/app/react'
+import { AppShell } from '@fabrika/ui'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { api } from './api'
+import { MyTasks } from './mine'
+
+const root = document.getElementById('root')
+if (root !== null) {
+	createRoot(root).render(
+		<StrictMode>
+			<FabrikaProvider clients={[api]}>
+				<AppShell
+					brand="Tasks"
+					nav={[{ label: 'My tasks', href: '/', active: true }]}
+				>
+					<MyTasks />
+				</AppShell>
+			</FabrikaProvider>
+		</StrictMode>,
+	)
+}
+```
+
+```ts build-web.ts
+import { shellSlicePlugin } from '@fabrika/check/bun-plugin'
+import { join } from 'node:path'
+
+const outdir = join(import.meta.dir, 'dist', 'web')
+const built = await Bun.build({
+	entrypoints: [join(import.meta.dir, 'web', 'index.html')],
+	outdir,
+	target: 'browser',
+	define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+	plugins: [shellSlicePlugin({ root: import.meta.dir })],
+})
+if (!built.success) {
+	for (const log of built.logs) console.error(String(log))
+	process.exit(1)
+}
+const index = Bun.file(join(outdir, 'index.html'))
+await Bun.write(
+	index,
+	(await index.text()).replaceAll(/(src|href)="\.\//g, '$1="/'),
+)
+```
+
+- The SPA imports `@fabrika/app/client`, `@fabrika/app/react`, `@fabrika/ui`, React, `fabrika.contract.ts`,
+  `src/schemas.ts`, `src/shared/` and its own modules; never a slice, `src/db/` or a Bun or Node module. The plugin loads the
+  contract without its handlers. A row type the screen declares (`Task` above) is checked against the answer where
+  the rows are passed in.
+- The last step points the page's assets at the SPA's prefix (`/`): the mount answers `index.html` for every path
+  under it, so a deep link such as `/tasks/<id>` renders. `define` gives React's production build.
+- Set text through JSX, never `dangerouslySetInnerHTML` or `innerHTML`. Same-origin calls carry the session cookie.
+- **Who is signed in.** Every member SPA serves `<prefix>/__fabrika-me.json` to the person it admitted:
+  `{ label, email, actions: { app, scopes } }`. `useCaller()` (`@fabrika/app/react`) answers `{ label, email,
+  can(action, scope?) }` from it, and `<Can action="tasks.write">` shows its children only when the token grants the
+  action. It comes from the token and asks IAM nothing. Use it to greet the person and to show or hide a control,
+  never as the check: every endpoint decides again, so a hidden button is no protection. A public SPA answers it 401,
+  because its pages arrive without a token, signed in or not.
+
+## Ignored files
+
+`.gitignore`: `node_modules/`, `fabrika.manifest.json`, `/fabrika/entry.generated.ts`, `/dist/`.

package/skill/references/dev.md

@@ -0,0 +1,90 @@
+# references/dev.md — previewing the application with `fabrika app dev`
+
+`bunx fabrika app dev` serves the application on `http://127.0.0.1:3000/` through its test kit: the proxy decision,
+the stand-in IAM, a throwaway schema of `FABRIKA_TEST_POSTGRES_URL`, and each SPA from its build (run
+`bun run build:web` first). Use it to look at the screens, never in place of a test.
+
+## The seed
+
+`dev/seed.ts` runs once, before the first request. It receives the kit, the API the tests use, writes through the
+endpoints, and answers whom and what the picker offers. `--seed=<module>` names another file.
+
+```ts dev/seed.ts
+import { createClient } from '@fabrika/app/client'
+import type { DevSeed } from '@fabrika/app/testing'
+import { contract } from '../fabrika.contract'
+
+const seed: DevSeed<typeof contract> = async (dev) => {
+	const acme = dev.scope('org', 'acme')
+	const ada = dev.testCaller([{ role: 'owner', scope: acme }], {
+		label: 'Ada Lovelace',
+		email: 'ada@acme.example',
+	})
+	const ben = dev.testCaller([{ role: 'member', scope: acme }], {
+		label: 'Ben Okafor',
+		email: 'ben@acme.example',
+	})
+	const api = createClient(contract, 'api', { fetch: dev.browser(ada) })
+	await api.projects.create({ orgId: acme.value, name: 'Website relaunch' })
+	await api.members.invite({
+		orgId: acme.value,
+		email: 'cleo@acme.example',
+		role: 'member',
+	})
+	return {
+		personas: [
+			{ name: 'Ada', description: 'Owns Acme: invites and assigns', caller: ada },
+			{ name: 'Ben', description: 'A member who works the tasks', caller: ben },
+		],
+		scopes: { org: [{ value: acme.value, label: 'Acme' }] },
+	}
+}
+
+export default seed
+```
+
+- A persona is a person the seed made with `dev.testCaller` (a session, never `via: 'key'`), with a unique `name` and
+  a one-line `description`. The picker shows its roles, the scope values it holds them in, and `external`.
+- `links` lists pages a link holder opens: `{ title, description, url }`, where `url` is what the application's own
+  endpoint answered from `ctx.links.issue` (`/s/#<key>`). Never build a link URL by hand.
+- `scopes` names the values the seed made, by dimension, with the label a person knows them by; the picker offers
+  them for a membership role.
+- Check every call the seed makes: an endpoint that refuses answers a status, and the seed goes on without its data.
+  Throw when one does: a seed that throws stops `app dev` and prints its error with the stack.
+- `dev.runJob('<job>')` runs a cron job from the seed (`app dev` runs none on its schedule). A job's `ctx.links` works:
+  the stand-in IAM takes the job's own key. What a job's handler throws is printed with its stack, here only.
+
+## Outside the application
+
+- `dev/dev.env` holds the application's variables for `app dev`, one `NAME=value` per line (`#` comments, quotes
+  optional). They win over the shell's; a `FABRIKA_*` name is refused. Commit it: it holds stand-in values, never a
+  real secret.
+- A form's challenge passes in `app dev`: the stand-in answers Turnstile's siteverify for any token. Set the form's
+  `secret` variable to any value in `dev/dev.env`, and send a fresh `challengeToken` with each submission, as a test
+  does: a token is single use. For the widget on a page, set the `siteKey` variable to Turnstile's always-passing test
+  key `1x00000000000000000000AA`. Its token is the same every time, and `app dev` admits that one token again at each
+  submission; a deployed application records it like any other, so there it passes once.
+- Point an outside provider at the dev outbox: `app dev` captures every request the process sends to
+  `https://outbox.invalid` (`DEV_OUTBOX_ORIGIN` of `@fabrika/app/testing`) and answers `200 {"id": …}`. The mail view
+  lists each one, by the `to` and `subject` of a JSON body, and opens its body; its headers are not kept.
+- The seed's second argument reads the outbox: `outside.outbox()` is every captured request, oldest first
+  (`{ id, method, path, contentType, body }`), so the seed can open a link the application mailed.
+
+```text dev/dev.env
+# Stand-in values for fabrika app dev.
+TURNSTILE_SECRET=dev
+TURNSTILE_SITE_KEY=1x00000000000000000000AA
+MAIL_API_URL=https://outbox.invalid/mail
+MAIL_API_KEY=dev
+```
+
+## In the browser
+
+- `/__fabrika/dev` is the picker: the personas, another role of the vocabulary (a membership role with a scope value),
+  anonymous, the link pages, and the mail: what IAM sent and what reached the dev outbox. It speaks the vocabulary's `locale` and shows its `displayName`.
+- Every SPA page carries a toolbar in the bottom corner: who you are, the personas to switch to (the page reloads as
+  that caller), the picker, the link pages, and the mail. An invitation's link accepts it; the browser is the invited
+  person from then on.
+- The choice stays in a cookie the application never sees. The data is gone when the command stops.
+- It serves this machine only (`--host` is a loopback address, `--port=0` picks a free port), answers no request
+  addressed to another host name, and runs no cron job on its schedule: the seed runs one with `dev.runJob`, a test with `kit.runJob`.