@fabrika/app 0.3.3 → 0.4.0

package/skill/references/start.md

@@ -0,0 +1,179 @@
+# references/start.md — a new application, before its first table
+
+A new application starts without tables: a vocabulary, a contract, one endpoint and its first test. It needs no
+database, no migration and no generated schema until it stores something. This file is an application of its own; its
+`package.json` and `tsconfig.json` are those of `app-setup.md`, without the `build:web` script until it has an SPA.
+
+## The files
+
+```ts src/vocabulary.ts
+import { defineVocabulary } from '@fabrika/app/contract'
+
+export const vocabulary = defineVocabulary({
+	app: 'tasks',
+	dimensions: {
+		org: { members: { manage: 'members.manage', list: 'tasks.read' } },
+	},
+	actions: {
+		'tasks.read': 'Read the tasks of an org',
+		'members.manage': 'Invite and remove members',
+	},
+	roles: {
+		owner: {
+			grants: ['tasks.read', 'members.manage'],
+			member: { scope: 'org', assignableBy: ['owner'] },
+		},
+	},
+})
+```
+
+```ts src/app-kit.ts
+import { defineApp } from '@fabrika/app/contract'
+import { vocabulary } from './vocabulary'
+
+export const app = defineApp(vocabulary)
+```
+
+```ts src/orgs/endpoints.ts
+import { z } from 'zod/v4'
+import { app } from '../app-kit'
+
+const MyOrgs = z.strictObject({ all: z.boolean(), orgs: z.array(z.string()) })
+
+export const orgs = app.group({ callers: ['human'] }, (r) => ({
+	mine: r.query({
+		output: MyOrgs,
+		access: { action: 'tasks.read', over: 'org' },
+	})
+		.handle(({ ctx }) =>
+			ctx.within.values === 'all'
+				? { all: true, orgs: [] }
+				: { all: false, orgs: [...ctx.within.values].sort() }
+		),
+}))
+```
+
+```ts fabrika.contract.ts
+import { app } from './src/app-kit'
+import { orgs } from './src/orgs/endpoints'
+
+export const contract = app.contract((c) => ({
+	api: c.rpc('/api', { orgs }),
+	health: c.health('/healthz'),
+}))
+```
+
+```ts src/app.ts
+import { serve } from '@fabrika/app/implement'
+import { contract } from '../fabrika.contract'
+
+export default serve(contract, { database: null })
+```
+
+- `defineApp(vocabulary)` declares no tables, so `serve` takes `database: null`, and only then. A handler has no
+  `ctx.db`, `ctx.sql` or `unscoped` (a type error that names `defineApp(vocabulary, tables)`); it answers from the
+  caller's grants (`ctx.within.values`, `ctx.principal`), the member directory, or a connector.
+- Forms, jobs and file collections keep their rows in tables, so an application gets them with its first table.
+
+```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'
+
+const compiled = compileContract(contract, {})
+
+const services = (): ZeropsServiceSpec[] => [
+	{
+		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',
+	},
+})
+```
+
+Without a PostgreSQL service the platform runs no `fabrika db migrate`, no codegen check and no generated test at
+start. `zerops.yaml` holds only `build.base` until the application has an SPA to build.
+
+## The first test
+
+`bunx fabrika db test-scaffold` writes nothing for this application and says so: the generated tests start with the
+first table (its policy test, then the endpoint access test over its rows). `bun test` fails on an application with no test file, and the platform's
+build runs it, so write the first test yourself:
+
+```ts src/__tests__/orgs.test.ts
+import { createClient } from '@fabrika/app/client'
+import { testKit } from '@fabrika/app/testing'
+import { describe, expect, test } from 'bun:test'
+import { contract } from '../../fabrika.contract'
+import app from '../app'
+
+const kit = testKit(app)
+
+describe('a new application', () => {
+	test('answers its health check', async () => {
+		expect((await kit.fetch('/healthz')).status).toBe(200)
+	})
+
+	test('lists the orgs a member works in, and refuses a caller of none', async () => {
+		const owner = kit.testCaller([
+			{ role: 'owner', scope: { type: 'org', value: 'acme' } },
+		])
+		const api = createClient(contract, 'api', { fetch: kit.browser(owner) })
+		expect(await api.orgs.mine()).toEqual({ all: false, orgs: ['acme'] })
+		const stranger = kit.browser(kit.testCaller([]))
+		const refused = await stranger('/api/orgs.mine', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: '{}',
+		})
+		expect(refused.status).toBe(403)
+	})
+})
+```
+
+The loop of `SKILL.md` without its database lines: `bun test --isolate` until it passes, then `bunx tsc --noEmit` and
+`bunx fabrika-check .` once each.
+
+## The first table
+
+When the application first stores something, in this order:
+
+1. Add the PostgreSQL service to `fabrika.config.ts` (`app-setup.md`). The platform then migrates at every start.
+2. `bunx fabrika db new <slug>` and the table's SQL (`table-and-migration.md`), then `bunx fabrika db migrate` and
+   `bunx fabrika db codegen`, which writes `src/db/schema.generated.ts`.
+3. `src/db/tables.ts` with the table's policy, over the generated `columns`.
+4. `defineApp(vocabulary, tables)` in `src/app-kit.ts`, `serve(contract, { database: scoped(tables) })` in
+   `src/app.ts`, and `compileContract(contract, tables)` in `fabrika.config.ts`.
+5. `bunx fabrika db test-scaffold`: it now writes the generated tests. Commit them.
+
+## The skill itself
+
+These rules ship in `@fabrika/app` (`node_modules/@fabrika/app/skill/`), at the version the application installed:
+read them there, or install them where an agent looks for skills.
+
+- `bunx fabrika builder init --profile zerops-app --no-daemon --no-open --agent=claude` (or `codex`, or `all`)
+  writes them under `.claude/skills/fabrika-app/` (`.agents/skills/fabrika-app/` for Codex) from the application's own
+  `@fabrika/app`, beside the builder's `fabrika` skill. It also creates the builder's `.fabrika/` and an empty
+  `tests/`. Run `bun install` first, or it installs the builder's copy and says so.
+- After you update `@fabrika/app`, run it again: it replaces the files it installed and keeps a file you edited.
+- An agent that reads `AGENTS.md` gets the same text, rendered by `renderAgentsFile` of `@fabrika/app/agent-skill`:
+  `bun -e "import { installedAppAgentSkill, renderAgentsFile } from '@fabrika/app/agent-skill'; const skill =
+  installedAppAgentSkill('.'); if (skill) await Bun.write('AGENTS.md', renderAgentsFile(skill))"`. Regenerate it
+  after each update; never edit it.

package/skill/references/table-and-migration.md

@@ -0,0 +1,264 @@
+# references/table-and-migration.md — the vocabulary, migrations and table policies
+
+The order is fixed: the vocabulary, then the migration, then `fabrika db migrate` and `fabrika db codegen`, then the
+table policies, which take the generated `columns`.
+
+## The vocabulary
+
+```ts src/vocabulary.ts
+import { defineVocabulary } from '@fabrika/app/contract'
+
+export const vocabulary = defineVocabulary({
+	app: 'tasks',
+	dimensions: {
+		org: { members: { manage: 'members.manage', list: 'tasks.read' } },
+		project: { in: 'org' },
+		task: { in: 'project' },
+	},
+	actions: {
+		'tasks.read': 'Read projects, tasks and comments',
+		'tasks.write': 'Create and edit projects, tasks and comments',
+		'tasks.assign': 'Assign a task to a member',
+		'members.manage': 'Invite and remove members',
+	},
+	roles: {
+		owner: {
+			grants: ['tasks.read', 'tasks.write', 'tasks.assign', 'members.manage'],
+			member: { scope: 'org', assignableBy: ['owner'] },
+		},
+		member: {
+			grants: ['tasks.read', 'tasks.write'],
+			member: { scope: 'org', assignableBy: ['owner'] },
+		},
+	},
+})
+```
+
+- A **dimension** is a kind of scope value. `in` is its container: every task lies in one project, every project in
+  one org. A grant on a container reaches everything inside it. A top-level dimension (`org`) is the value IAM grants
+  roles in; no table needs to own it.
+- An **action** is an exact name; a role lists actions and there is no `*`. Give an operation that only some roles
+  may do its own action (`tasks.assign`).
+- A **membership role** (`member: { scope, assignableBy }`) is granted in one value of `scope`. `assignableBy` names
+  who may give it there: a membership role of the same `scope`, held in that value, or a role with no `member`, which
+  IAM grants app-wide (`staff`), held globally. Holding the role is not enough: IAM also requires `members.manage` and
+  every action of the role given in that value, which a global grant covers. `external: true` on
+  one lets a person from outside the organization (a partner's account) hold it; IAM gives such a person no other
+  role. `{ member: true }` then admits them too, so a staff-only endpoint names an action only internal roles grant.
+  `ctx.members` answers each member's `affiliation`.
+  `members: { manage, list }` on a dimension gives `ctx.members` to the endpoints on, in or below it: a lookup of one
+  member everywhere, the list with `list`, management with `manage` (`references/endpoint.md`).
+- `admin` is reserved: IAM defines it for every application. `defineVocabulary` refuses it.
+- `locale: 'cs'` (or `'en'`) and `displayName: 'Tasks'` beside `app` set the language and the name IAM uses for the
+  application on its sign-in, password and invitation pages and e-mails. Without `locale` IAM speaks its default
+  language, `en`. Without `displayName` the sign-in and password pages and mails name no application, and an invitation
+  names it by its id (`tasks@prod`). The approver sees each change.
+- `mail` beside them words IAM's e-mails in the application's own way: per message (`invitation`, `enrollment`,
+  `reset`) and language, a one-line `subject` and a plain `text` with `{{name}}` placeholders, for example
+  `mail: { reset: { cs: { subject: 'Nové heslo do {{displayName}}', text: 'Heslo si nastavíte zde:\n{{actionUrl}}' } } }`.
+  The text must hold `{{actionUrl}}`, the one-time link IAM builds, and the subject must not. Without `html` IAM writes
+  the HTML part itself. Every message fills
+  `{{displayName}}`, `{{recipient}}`, `{{actionUrl}}`, `{{appUrl}}` and `{{expiry}}`; an invitation also `{{inviterLabel}}`,
+  `{{companyLabel}}` and `{{message}}`. Another placeholder is refused. A message or language without a template is IAM's
+  own wording.
+- An `html` beside `subject` and `text` is the message's own HTML body, in a closed subset: `<p>`, `<br>`, `<strong>`,
+  `<b>`, `<em>`, `<i>`, `<u>`, `<span>`, `<div>`, `<h1>`–`<h3>`, `<ul>`, `<ol>`, `<li>`, `<blockquote>`, `<hr>` and
+  `<a>`, lower case and balanced, with no attribute but a link's double-quoted `href`, which is exactly
+  `{{actionUrl}}`, `{{appUrl}}` or a `mailto:` address. It holds at least one `<a href="{{actionUrl}}">`. No style,
+  image, script, form, frame, comment or other origin: the checker and IAM's reconcile refuse each, and IAM escapes every
+  value it fills in. `{{appUrl}}` is the application's first registered return origin; until one is registered, a
+  template that names it is sent in IAM's own wording.
+- `creator: '<role>'` on a top-level dimension lets an endpoint with `creates: '<dimension>'` make a new value and
+  grant the caller that role there.
+
+## The migration
+
+```sql db/migrations/20261012090000_tasks.sql
+-- An org is the scope IAM grants roles in; no table owns it. Every contained table repeats its container's chain and
+-- references UNIQUE (id, <chain>) of its container, so a moved project moves its tasks.
+CREATE TABLE projects (
+	id UUID PRIMARY KEY,
+	org_id TEXT NOT NULL,
+	name TEXT NOT NULL,
+	created_by TEXT NOT NULL,
+	version INTEGER NOT NULL,
+	UNIQUE (id, org_id)
+);
+CREATE INDEX projects_org ON projects (org_id);
+
+CREATE TYPE task_status AS ENUM ('open', 'doing', 'done');
+
+CREATE TABLE tasks (
+	id UUID PRIMARY KEY,
+	project_id UUID NOT NULL,
+	org_id TEXT NOT NULL,
+	title TEXT NOT NULL,
+	status task_status NOT NULL DEFAULT 'open',
+	assignee TEXT,
+	assignee_label TEXT,
+	due_on DATE,
+	overdue BOOLEAN NOT NULL DEFAULT false,
+	created_by TEXT NOT NULL,
+	version INTEGER NOT NULL,
+	UNIQUE (id, project_id, org_id),
+	FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE
+);
+CREATE INDEX tasks_project ON tasks (project_id);
+
+CREATE TABLE task_comments (
+	id UUID PRIMARY KEY,
+	task_id UUID NOT NULL,
+	project_id UUID NOT NULL,
+	org_id TEXT NOT NULL,
+	body TEXT NOT NULL,
+	created_by TEXT NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+	FOREIGN KEY (task_id, project_id, org_id) REFERENCES tasks (id, project_id, org_id) ON UPDATE CASCADE ON DELETE CASCADE
+);
+CREATE INDEX task_comments_task ON task_comments (task_id);
+
+CREATE TABLE project_exports (
+	id UUID PRIMARY KEY,
+	project_id UUID NOT NULL,
+	org_id TEXT NOT NULL,
+	row_count INTEGER NOT NULL,
+	created_by TEXT NOT NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+	FOREIGN KEY (project_id, org_id) REFERENCES projects (id, org_id) ON UPDATE CASCADE ON DELETE CASCADE
+);
+CREATE INDEX project_exports_project ON project_exports (project_id);
+
+-- A code list: shared rows that every endpoint reads, and only a migration writes.
+CREATE TABLE priorities (
+	code TEXT PRIMARY KEY,
+	label TEXT NOT NULL,
+	rank INTEGER NOT NULL
+);
+INSERT INTO priorities (code, label, rank) VALUES ('low', 'Low', 1), ('normal', 'Normal', 2), ('high', 'High', 3);
+```
+
+- `bunx fabrika db new <slug>` writes `db/migrations/<UTC YYYYMMDDHHMMSS>_<slug>.sql`. Without a shell, use that name.
+- The key is `id`. A contained table has `<container>_id` and every column of its container's chain (`project_id`,
+  `org_id`), `UNIQUE (id, <chain>)`, and a composite foreign key `(<container>_id, <chain>) → <container
+  table> (id, <chain>)`. A child table (`task_comments`) does the same with its parent. Without the composite key the
+  table policy is refused, and an `over` list cannot reach the table from an outer dimension.
+- `version INTEGER NOT NULL` makes `expectVersion` and the 409 work; `created_by TEXT NOT NULL` with `createdBy` in
+  the policy records the caller. The data layer generates `id` and writes `version` and `created_by`.
+- A column with a fixed set of values is an `ENUM` type, not a `CHECK` on text: the generated tests fill text columns
+  with markers, which a `CHECK` refuses.
+- Codegen types: `date` is a `YYYY-MM-DD` string; `timestamptz` reads a `Date` and takes a `Date` or a strict ISO 8601 string with `Z` or an offset;
+  `int8` and `numeric` are strings; an enum is its literal union. JSON, `bytea`, arrays and domains are refused.
+- Plain SQL of the application's own schema only. Refused: another schema (`public.`, `app_…`), any `fabrika_*`
+  object (except a file collection's table, `references/files.md`), `GRANT`, roles, `CREATE EXTENSION`, `COPY`,
+  `SET`, transaction control, `SECURITY DEFINER`, a domain, `serial` and sequences (use `GENERATED ALWAYS AS IDENTITY`),
+  a function overload, and calls outside the reviewed built-ins.
+- Never edit, rename or delete a committed migration; add a new one. Change a schema by expand, switch, contract, and
+  ask before you drop or rename anything.
+
+## Database code is a declared deviation
+
+A function, trigger, view, rule, policy or `DO` block in a migration is allowed. The migration file declares it, and
+the approver sees it marked "needs closer review". Prefer a handler when the rule is the application's; use database
+code when it must hold for every writer.
+
+```sql db/migrations/20261012110000_done_clears_overdue.sql
+CREATE FUNCTION tasks_done_clears_overdue() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+	IF NEW.status = 'done' THEN
+		NEW.overdue := false;
+	END IF;
+	RETURN NEW;
+END
+$$;
+
+CREATE TRIGGER tasks_done_clears_overdue BEFORE UPDATE ON tasks
+	FOR EACH ROW EXECUTE FUNCTION tasks_done_clears_overdue();
+```
+
+The platform runs `fabrika db codegen --verify` at every start; it fails when the schema holds database code that no
+migration declares.
+
+## The table policies
+
+```ts src/db/tables.ts
+import { defineTables } from '@fabrika/db/tables'
+import { vocabulary } from '../vocabulary'
+import { columns } from './schema.generated'
+
+export const tables = defineTables(vocabulary, columns)({
+	projects: {
+		scope: { dimension: 'project' },
+		actions: { read: 'tasks.read', insert: 'tasks.write', update: 'tasks.write' },
+		insert: ['name'],
+		update: ['name'],
+		version: 'version',
+		createdBy: 'created_by',
+	},
+	tasks: {
+		scope: { dimension: 'task' },
+		actions: {
+			read: 'tasks.read',
+			insert: 'tasks.write',
+			update: 'tasks.write',
+			delete: 'tasks.write',
+		},
+		insert: ['title', 'due_on'],
+		update: ['title', 'status', 'due_on', 'overdue'],
+		version: 'version',
+		createdBy: 'created_by',
+		columns: {
+			assignee: { write: 'tasks.assign' },
+			assignee_label: { write: 'tasks.assign' },
+		},
+	},
+	task_comments: {
+		scope: { child: 'tasks' },
+		actions: { read: 'tasks.read', insert: 'tasks.write' },
+		insert: ['body'],
+		createdBy: 'created_by',
+	},
+	project_exports: {
+		scope: { child: 'projects' },
+		actions: { read: 'tasks.read', insert: 'tasks.read' },
+		insert: ['row_count'],
+		createdBy: 'created_by',
+	},
+	priorities: {
+		scope: { reference: 'the priority codes; a migration changes them' },
+		actions: { read: 'tasks.read' },
+	},
+})
+```
+
+- Every table has a policy. Its scope is one of: `{ dimension: '<d>' }` (the table owns the dimension's values),
+  `{ child: '<table>' }` (rows that belong to one row of the parent), `{ app: '<why>' }` (rows of the whole
+  application, such as a code list an administrator edits) or `{ reference: '<why>' }` (shared rows every endpoint
+  reads and none writes; a migration changes them).
+- An application table takes `actions`, `insert`, `update`, `version`, `createdBy` and `columns` like a dimension
+  table, and no container. An `app: true` endpoint reads and writes it (`ctx.db.app.<table>`, `references/endpoint.md`),
+  for a caller who holds the operation's action as a global grant. An `on`, `in` or `over` endpoint whose action is
+  its read action reads it, every row and read-only, so its read action decides who reads it.
+- A reference table (`priorities`) takes `actions: { read: '<action>' }` and, at most, `columns` with read actions: no
+  `insert`, `update`, `version` or `createdBy`. Its rows change by a migration only. No handle writes it, and
+  `unscoped: { priorities: 'write' }` is refused by tsc and the checker.
+- The key (`id`), the container column (`<container>_id`), a child's column (`<parent dimension>_id`) and the chain
+  are derived. State `in: { column }` or `column` only off that convention.
+- `actions` maps `read`, `insert`, `update` and `delete` to vocabulary actions. `insert` and `update` list the columns
+  that those actions write; nothing else is writable.
+- A dimension or child table may also list `appRead: ['<action>', …]`, actions besides `read` with which an `app: true`
+  endpoint lists every row, read-only (an export, a bulk send), with the columns of that action, and
+  `appCount: ['<action>', …]`, actions with which it only counts rows (`count({ where })`) and reads none, no aggregate
+  (an operations counter). Each is a widening the approver sees.
+- `columns: { <column>: { read: '<action>' } }` hides a column from every capability of another action, in the data
+  and in the types. `columns: { <column>: { write: '<action>' } }` lets only that action update the column (and that
+  action updates nothing else); the column is then not in `update`.
+- A column has one write action. A state that two actions change is two columns: in `references/public-intake.md` the
+  link holder's `candidates.verify` sets `verified_at`, HR's `candidates.review` sets `status`, and `logic.ts` derives
+  the stage HR sees from both (`stageOf`).
+- An audit or history table is an ordinary child table that a handler writes in its own transaction:
+  `project_exports` logs each export of a project's tasks, so its insert action is the export's read action
+  (`references/endpoint.md`). The log of an export across every record is an application table instead
+  (`references/public-intake.md`). There is no framework audit API.
+- IAM already audits sign-ins (its auth log, refusals included) and every grant and revocation (its admin events
+  `iam.grant.create` and `iam.grant.revoke`): do not rebuild either in the application. An operator's access to the
+  database or to the provider's console is outside Fabrika.