Working on this app

You are one of the crew on this repository. The forge runs the app for you: production follows the default branch, and every pull you open gets a preview at its own address, deployed from your branch as you push.

The rules

• Work on the branch you were given. You cannot move the default branch;

a person merges your pull once it is reviewed.

• Keep state under FORGE_APP_DATA. Never write elsewhere at runtime.
• Run bun test before you push. forge.json's app.test runs it beside

the app on every deploy, not before it: the preview comes up the moment the app answers and says live, or serving · tests failed the moment the suite disagrees. Every behaviour you add gets a test that would fail without it.

• src/tty.ts is the app's terminal. The exact command that reaches it is

FORGE_APP_SSH at runtime; print that verbatim wherever the app tells people how to connect. What a person can do on the page they can do here, and nothing more: the terminal gates its reads and writes exactly as the page does (FORGE_APP_USER_ROLE is the forge's word on who is there), and a write made there reaches web viewers live like any other.

• Keep it dependency-free unless a dependency is clearly worth it, and say

why in the pull. A dependency is code you now maintain.

• When you are done, push and stop. Your last message becomes the pull's

description: say what changed, what you chose not to do, and what to look at in the preview.

The shape

One implementation, many doors. Every operation is a function in src/actions.ts — (db, who, input) in, data or a named failure out — and the page (src/routes.ts, src/page.ts), the JSON API (src/routes.ts), the MCP server (src/mcp.ts) and the terminal (src/tty.ts) call it. A door reads its wire format and shapes the answer; it decides nothing. A rule in an action holds at every door at once; a rule anywhere else is a bug waiting for the door you forgot.

Identity comes from the forge (src/who.ts): anon, user or admin, verified by signature, never by a cookie the app invents.

Every request passes the door (src/security.ts) before a route sees it: writes are rationed, a write from another site is refused, and a request under a resource's api path is refused — before its body is read — when the table lets that person through that door for no row at all. The door asks the same table the actions do; it never compares roles by hand, and the action still decides about the real row. Do not route around it.

Every change is written down. An action that creates, updates or deletes returns through audited (src/actions.ts), which appends a row to the audit table — who, the resource and verb, the row, when, and whether they were let — refused attempts included; the door records the writes it turns away. Admins read it at GET /api/audit (the audit resource in contract.json). Recording never fails a request: a row that cannot be written is a log line.

Who may do what is a table, not code: contract.json. It declares the roles — each names the roles below it, and how it is held: by everyone, by the identity the forge signed, or by a row's column naming the person — and, for every resource, the least role each of create, read, update, delete and list needs. An action asks permit(who, resource, verb, row) (src/contract.ts) and obeys the answer; it never compares who.role itself. src/can.ts is the forge's evaluator, carried verbatim: do not edit it. src/contract.test.ts acts as every identity at every door and fails when a door and the table disagree.

A new kind of person is a new role in the table, under an existing one. A change to a cell is a change of policy: say so in the pull's description. A cell loosened — anything an identity could not do before that it can after — is a wall: the forge shows the pull to a person and never lands it on its own. Do not loosen a cell unless the issue asks for exactly that; prefer a new role under an existing one, or a new resource, to widening a door that was decided.

To add a concept:

• An action — a function in src/actions.ts that asks permit, its

resource's row in contract.json, its door in src/contract.test.ts, and a test in src/actions.test.ts for what the table cannot say.

• A migration — append to migrations in src/db.ts. Never edit one

that has run. bun run src/db.ts --check shows the version.

• A page — a row in src/routes.ts and a function in src/page.ts.

With a second page, move them under src/pages/ and keep one layout.

• An API route — a row in src/routes.ts that calls the action and

answers with answer(...); the status follows the failure. Give it an api entry beside it (a sentence, the body and answer as JSON Schema) and run bun run contract:emit: contract/openapi.json is committed, served at /openapi.json, and bun test fails while it is stale. A resource's routes live under the api path its contract.json entry names, so the door and the forge's probe find them.

• A tool — an entry in tools in src/mcp.ts: a name, one sentence,

a JSON schema, the action.

• A terminal command — a key in src/tty.ts that calls the action and

reports on the status line.

• Something live — emit(type, data) in the action, and

data-live="<types>" on the region of the page that shows it.

• A colour, a space, a size — a token in design/tokens.json (a

colour needs its dark value in $extensions.mode.dark), used as var(--…). bun run lint:design refuses a raw #hex, rgb( or hsl( anywhere in src/ or static/, and a var(--…) that names no token; src/design.test.ts runs it, and holds every pair of colours a person reads to 4.5:1 in both themes.

The bar

• Security: every input is validated at the boundary and every output is

escaped; every response carries the floor in src/http.ts (keep it, extend it); a POST that is not same-origin is refused; writes are rationed per person; secrets come from the environment (Settings → App → Environment), never the repository; no eval, no shell built from user text. A request body is capped by the bytes actually read (readBody), never by a Content-Length. HEAD answers like GET. A private thing needs an identity from who, and a cookie the app sets itself is HttpOnly; SameSite=Lax.

• Speed: the first paint is server-rendered HTML; JavaScript is small, in

static/, linked by content (asset()) and cached for a year; no layout shift; what changes arrives over /events, never by polling; work that can wait is done after the response.

• A phone is a first-class client: the page works at 360px wide with no

horizontal scroll, every control is at least 44px on a side (--size-tap), an input's text is never below 16px (a phone zooms into a smaller one), focus is always visible, whoever asked for less motion gets none, and the keyboard reaches everything a mouse does.

• Beauty is the tokens': light and dark both, from one file. A new page

uses layout, which carries the tokens, the description and the Open Graph and card metadata a shared link unfurls with — pass the page's path so og:url is its own.

• Finish: the app boots, /healthz answers { ok, version, uptime }

(the forge polls it; keep it cheap and apart from the page), / answers, bun test is green, the README says how to use it and what is real versus simulated, forge.json says how to run it.