@fougere/app 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/form.ts

@@ -1,30 +1,15 @@
 import { Lifecycle } from '@fougere/schema';
 /**
- * Form contract, pure part — derives what a create/edit form is made of
- * from the entity's field axes. No Vue, no Nuxt: testable headless,
- * usable by any renderer (the page owns the widgets).
+ * Form contract, pure part — derives what a create/edit form is made of from the entity's field
+ * axes.
  */
-import { Anatomy, lowerFirst, Role, Visibility } from '@fougere/schema';
+import { Shapes, lowerFirst, Role, Visibility } from '@fougere/schema';
 import type { Field, SchemaView, ValidationError, ValidationResult } from '@fougere/schema';
 
-/**
- * What an entity class exposes to a form — the schema statics it already has.
- *
- * `SchemaView` and the real `Field`, not a local re-description of the axes: this file
- * used to declare its own `FieldLike` with `shape?` optional, so it kept judging by a
- * looser contract than the schema's own and would never have seen `shape` become
- * required.
- */
+/** What an entity class exposes to a form — the schema statics it already has. */
 export type FormEntity = SchemaView;
 
-/**
- * The literal a field is born with, when it declares one.
- *
- * `text({ default: 'x' })` and `oneOf('a', 'b', { default: 'a' })` both compile to
- * `lifecycle.create = { value }` — the create rule that answers the field's absence.
- * The other create rules ('now', { generate }, 'optional') name no literal: their value
- * is decided at write time, so a form has nothing to show for them.
- */
+/** The literal a field is born with, when it declares one. */
 function defaultOf(field: Field): unknown {
   return Lifecycle.of(field).literal?.value;
 }
@@ -41,28 +26,8 @@ export interface FormField {
   /** Enum values, when control is 'select'. */
   options?: string[];
   /**
-   * What the browser enforces, under the names it already knows — spread this on the
-   * input and the page states no rule of its own.
-   *
-   * The shape holds `minLength`/`maximum`/`pattern`; a browser holds `minlength`/
-   * `max`/`pattern` and enforces them with no JavaScript at all. Carrying them here
-   * is a projection, not a second rule: the judge reads the same shape, and a form
-   * that ignores these still gets the same verdict — it just gets it later, and a
-   * screen reader never gets it at all.
-   *
-   * `type` is part of the contract, not decoration: `email` and `url` are formats the
-   * shape states and the browser checks live, per field, as one types. A page writing
-   * `type="email"` by hand is spelling a second time what the card already said.
-   *
-   * Three deliberate absences, each one a place where the attribute would mean
-   * something the shape does not say:
-   * - a `date` field gets no `type` — neither `date` nor `datetime-local` produces the
-   *   RFC 3339 string a `date-time` shape judges, so the browser would accept what the
-   *   judge refuses;
-   * - `select` and `boolean` are not inputs — the page picks the widget, `control` says
-   *   which;
-   * - a required `boolean` gets no `required` — on a checkbox that attribute means
-   *   "must be CHECKED", where the shape only says the value must be supplied.
+   * What the browser enforces, under the names it already knows — spread this on the input and the
+   * page states no rule of its own.
    */
   attrs?: {
     type?: 'text' | 'email' | 'url' | 'number';
@@ -73,11 +38,7 @@ export interface FormField {
     max?: number;
     pattern?: string;
   };
-  /**
-   * The value the field is born with — the literal its `lifecycle.create` rule names.
-   * Present so the form can SHOW what is about to be written; the storage realizes it
-   * either way, so a form that ignores this still produces the same row.
-   */
+  /** The value the field is born with — the literal its `lifecycle.create` rule names. */
   default?: unknown;
 }
 
@@ -87,7 +48,7 @@ function baseType(type: unknown): string {
   return (type as string) ?? 'string';
 }
 
-/** The formats a browser has an input type for — the rest stay `text`, judged later. */
+/** The formats a browser has an input type for — the rest stay `text`, validated later. */
 const CONTROL_BY_FORMAT: Record<string, FormField['control']> = {
   'date-time': 'date',
   email: 'email',
@@ -98,7 +59,7 @@ function controlOf(field: Field): FormField['control'] {
   // Through `anatomy`, never `shape.type` directly: the nullable form is the `[T,'null']`
   // union, which a direct comparison misses in silence. It is also what narrows the shape
   // union, so `enum` and `format` are only reachable on the branches that carry them.
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   if (base?.type === 'string' && base.enum?.length) return 'select';
   if (base?.type === 'number' || base?.type === 'integer') return 'number';
   if (base?.type === 'boolean') return 'boolean';
@@ -108,7 +69,7 @@ function controlOf(field: Field): FormField['control'] {
 
 /** A closed set's members, when the shape declares one — `oneOf('draft','live')`. */
 function enumOf(field: Field): readonly (string | null)[] | undefined {
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   return base?.type === 'string' ? base.enum : undefined;
 }
 
@@ -117,7 +78,7 @@ const INPUT_TYPES = new Set(['text', 'email', 'url', 'number']);
 
 /** The shape's bounds, under the names a browser already enforces. */
 function attrsOf(field: Field, control: FormField['control'], required: boolean): NonNullable<FormField['attrs']> {
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   const text = base?.type === 'string' ? base : undefined;
   const numeric = base?.type === 'number' || base?.type === 'integer' ? base : undefined;
   const attrs = {
@@ -140,11 +101,7 @@ function labelOf(name: string, entityKey: string): Pick<FormField, 'labelKey' |
   return { labelKey: `${entityKey}.${name}`, label: name.charAt(0).toUpperCase() + name.slice(1) };
 }
 
-/**
- * The fields a create form is made of: membership from the io projection
- * (`Visibility.input` — what a client may supply), requiredness from the
- * lifecycle axis (any create rule makes absence legal).
- */
+/** The fields a create form is made of. */
 export function formFieldsOf(entity: FormEntity, entityKey: string): FormField[] {
   return Object.entries(Visibility.of(entity.getFields()).input).map(([name, field]) => {
     const f = field;
@@ -175,18 +132,14 @@ export interface TableColumn {
   /** The same key a form uses for the same field — one convention, two projections. */
   labelKey: string;
   label: string;
-  /**
-   * The entity a `link` points at, under the key its door is named by. Always present on a
-   * reference: the card carries the target's name, and a card rebuilt with no sibling to
-   * resolve to keeps it as a stand-in rather than losing it.
-   */
+  /** The entity a `link` points at, under the key its door is named by. */
   to?: string;
 }
 
 /** Asked of the relation before the shape: a reference's own shape is a bare string. */
 function renderOf(field: Field): TableColumn['render'] {
   if (Role.of(field).isReference) return 'link';
-  const base = Anatomy.of(field.shape).base;
+  const base = Shapes.of(field.shape).base;
   if (base?.type === 'number' || base?.type === 'integer') return 'number';
   if (base?.type === 'boolean') return 'boolean';
   if (base?.type === 'object' || base?.type === 'array') return 'json';
@@ -194,13 +147,7 @@ function renderOf(field: Field): TableColumn['render'] {
   return 'text';
 }
 
-/**
- * The columns a list is made of: membership from the io projection (`Visibility.output` — what
- * may leave), minus collections, because a cell holds one value and a `many()` is a page.
- *
- * Which column identifies the row is NOT answered here — `FieldSet.primary` answers it for a
- * shape, and its own doc records what five private copies of that loop cost.
- */
+/** The columns a list is made of. */
 export function tableColumnsOf(entity: FormEntity, entityKey: string): TableColumn[] {
   return Object.entries(Visibility.of(entity.getFields()).output)
     .filter(([, field]) => !Role.of(field).isCollection)
@@ -216,9 +163,9 @@ export function tableColumnsOf(entity: FormEntity, entityKey: string): TableColu
 }
 
 /**
- * The wire body of the form's values — an empty control is an absent value
- * at the create boundary (absence is judged by the lifecycle axis, an empty
- * string would be judged as a present bad value).
+ * The wire body of the form's values — an empty control is an absent value at the create boundary
+ * (absence is validated by the lifecycle axis, an empty string would be validated as a present bad
+ * value).
  */
 export function payloadOf(values: Record<string, unknown>): Record<string, unknown> {
   return Object.fromEntries(
@@ -226,7 +173,7 @@ export function payloadOf(values: Record<string, unknown>): Record<string, unkno
   );
 }
 
-/** Index judge errors by field — local judge and remote judge share this shape. */
+/** Index validator errors by field — local validator and remote validator share this shape. */
 export function errorsByField(errors: ValidationError[]): Record<string, string> {
   const byField: Record<string, string> = {};
   for (const err of errors) {

package/src/graphql.ts

@@ -1,25 +1,4 @@
-/**
- * The GraphQL door — declared like the others, mounted like the others.
- *
- * Until now GraphQL was the odd one out: `adapters: { graphql: true }` was
- * declarable and nothing read it, while an app that wanted a schema wrote fifteen
- * lines of its own (a Pothos builder, a query type, a mutation type, `registerAll`,
- * then `registerGraphQL` on a router). Every one of those lines is convention —
- * there is no decision in them — so the app declaring the adapter is enough.
- *
- * The package is imported LAZILY, the same shape `db: 'sqlite'` uses (`resolveStorage`
- * pulls `@fougere/adapter-sql` only when a database is declared). A schema builder is
- * heavy and most apps serve none, so a host must not carry one to find out. Declaring
- * the adapter without installing it is refused by name, the way an unresolvable dialect is.
- *
- * This file used to BUILD the schema — a Pothos builder, `registerAll`, then `graphql()`
- * — which made it the only schema constructor in the repo, in the package least entitled
- * to be one. Two costs, one cause: the derivation sat away from the adapter whose job it
- * is, and `graphql` guards its types with `instanceOf`, so a schema built on one side of
- * the package boundary was refused on the other as coming *"from another module or
- * realm"*. Both are gone: `@fougere/adapter-graphql` derives and executes, this door
- * translates the result into an `Outcome`.
- */
+/** The GraphQL door — declared like the others, mounted like the others. */
 import type { App } from '@fougere/core';
 import type { Outcome } from './serve.js';
 
@@ -56,12 +35,7 @@ async function executor(): Promise<ExecuteOn> {
   }
 }
 
-/**
- * Execute a GraphQL request against the app's own operations.
- *
- * `pass` when the app declares no GraphQL adapter — the same answer `serveRest` gives,
- * so a host that mounted the door takes nothing away from an app that did not ask for it.
- */
+/** Execute a GraphQL request against the app's own operations. */
 export async function serveGraphQL(app: App, request: GraphQLRequest): Promise<Outcome> {
   if (!app.adapters?.graphql) return { kind: 'pass' };
 

package/src/index.ts

@@ -1,20 +1,9 @@
-/**
- * `@fougere/app` — what an app host needs and what no host owns.
- *
- * Two adapters read this package: `@fougere/nuxt` and `@fougere/next`. Between
- * them they share the boot, the three doors' decisions, the REST table, the form
- * contract and the session view; what they do NOT share is how a request arrives,
- * how routes are mounted, and how a value becomes reactive.
- *
- * The root entry pulls in the boot, which reads the filesystem — client code wants
- * `@fougere/app/client`.
- */
+/** `@fougere/app` — what an app host needs and what no host owns. */
 export {
   configureFougere,
   extendFougere,
   useFougereApp,
   reloadFougere,
-  createMemoryOrm,
   type FougereServerConfig,
 } from './boot.js';
 
@@ -53,3 +42,6 @@ export { sessionViewOf, type SessionView } from './session.js';
 export { stateFor } from './state.js';
 
 export { serveGraphQL, type GraphQLRequest } from './graphql.js';
+
+// Re-exported where every host already looks for it; it lives in its own adapter now.
+export { createMemoryStorage } from '@fougere/adapter-memory';

package/src/rest.ts

@@ -1,12 +1,4 @@
-/**
- * The REST table this app serves, and the rule that matches a request against it.
- *
- * Separated from the h3 handler on purpose: this file holds the whole of what the door
- * DECIDES — which operation a verb and a path name — while `api/crud.ts` only translates
- * that decision into h3. The rule was previously inline, untested, and had drifted into a
- * second REST projection that answered differently from `schema-rest` on all three counts
- * (verb, path, exposure).
- */
+/** The REST table this app serves, and the rule that matches a request against it. */
 import { generateRoutes } from '@fougere/adapter-rest';
 import type { App } from '@fougere/core';
 
@@ -31,14 +23,7 @@ export type RouteMatch =
 // it changes exactly when the app does.
 const tables = new WeakMap<App, Matchable[]>();
 
-/**
- * The table, per frond.
- *
- * `generateRoutes` prefixes every path the same way, while this door addresses a frond by
- * name (`/api/{frond}/{plural}`) — so it runs once per frond, each with its own prefix and
- * a filter naming it. That frond loop is the only thing this file knows that `schema-rest`
- * does not; the verbs, the paths and the membership rule all come from there.
- */
+/** The table, per frond. */
 export function tableOf(app: App): Matchable[] {
   const cached = tables.get(app);
   if (cached) return cached;
@@ -78,25 +63,10 @@ function openness(route: Matchable): number {
   return route.segments.filter((s) => s.startsWith(':')).length;
 }
 
-/**
- * Verbs this door accepts in place of the one the table names.
- *
- * `deriveMethod` gives `update` a single verb, PUT, while this door has always served
- * PATCH on it too — and says so (`docs/infra/surfaces`, "PUT · PATCH"). An alias keeps
- * that promise without giving the table a second row: both are mutations on a row, so
- * nothing is widened, and the one thing the table decides — WHICH operation a path names —
- * is still decided there alone.
- */
+/** Verbs this door accepts in place of the one the table names. */
 const ALIASES: Record<string, string> = { PATCH: 'PUT' };
 
-/**
- * Path first, method second — a router's order, and what makes a 405 possible at all.
- *
- * The order matters where the two overlap: `/posts/publish` and `/posts/:id` both accept
- * `GET /posts/publish`. Taking the most specific path first means the answer is "that verb
- * is refused here", not `findById('publish')` — and never `publish()`, which is what this
- * door used to do with the caller's session cookie attached.
- */
+/** Path first, method second — a router's order, and what makes a 405 possible at all. */
 export function matchRoute(table: Matchable[], method: string, segments: string[]): RouteMatch {
   const matches = table
     .map((route) => ({ route, params: paramsOf(route, segments) }))

package/src/serve.ts

@@ -1,16 +1,4 @@
-/**
- * The three doors, decided — and nothing about how a request arrives.
- *
- * A host (Nuxt, Next) owns exactly two translations: read the request into the
- * plain values below, and write the outcome back out. Everything between — which
- * operation a verb and a path name, which audience a segment selects, what a
- * refusal becomes — is decided here, once, for every host.
- *
- * The split matters because the alternative was measured in this repo: two copies
- * of a REST rule drifted until the Nuxt door answered differently from
- * `schema-rest` on the verb, the path AND the exposure. A second host would have
- * been a third copy.
- */
+/** The three doors, decided — and nothing about how a request arrives. */
 import {
   createAppRunner,
   callValueOf,
@@ -29,11 +17,7 @@ export interface DoorRequest {
   path: string;
   query: Record<string, string>;
   body?: unknown;
-  /**
-   * The server-resolved session. Stamped by the host from what IT resolved —
-   * never taken from the wire, which is the whole trust boundary of the browser
-   * door (`transport/http/src/server.ts` carries the same warning for the split).
-   */
+  /** The server-resolved session. */
   state: Record<string, unknown>;
 }
 
@@ -46,31 +30,16 @@ export type Outcome =
 
 // ── The call envelope ────────────────────────────
 
-/**
- * The audience this door serves — the path segment after `/_fougere/call`.
- *
- * The envelope is a surface like REST and GraphQL, so it selects its audience like
- * they do; the difference is only that it takes it from the path instead of an
- * option, because a door is mounted, not called. The same word names the directory
- * (`handlers/public/`), the config key (`surfaces: { public: [...] }`) and this
- * segment — derived, never configured.
- *
- * No escalation to guard: a named surface serves the entities it names and nothing
- * else (closed by naming), so every one of them is a subset of what the bare path
- * already serves.
- */
+/** The audience this door serves — the path segment after `/_fougere/call`. */
 export function surfaceOf(path: string): string | undefined {
   const named = /^\/_fougere\/call\/([A-Za-z0-9_-]+)/.exec(path.replace(/\?.*$/, ''));
   return named?.[1];
 }
 
 /**
- * Receiving end for the browser — same wire as process-to-process (JSON-RPC),
- * different trust boundary: the browser sits outside the topology, so `state` is
- * whatever the host resolved server-side, never what the payload claims.
- *
- * The runner follows the app's topology: local façades and remote doublures alike
- * — the browser never knows where a Frond lives.
+ * Receiving end for the browser — same wire as process-to-process (JSON-RPC), different trust
+ * boundary: the browser sits outside the topology, so `state` is whatever the host resolved
+ * server-side, never what the payload claims.
  */
 export async function serveRpc(app: App, request: Pick<DoorRequest, 'path' | 'body' | 'state'>): Promise<unknown> {
   const runner = createAppRunner(app, surfaceOf(request.path));
@@ -85,12 +54,7 @@ export function rpcParseError() {
 // ── REST ─────────────────────────────────────────
 
 /**
- * Match the URL against the canonical table, invoke the call it names, shape the
- * result for HTTP. The decision lives in `rest.ts`; dispatch belongs to the runner.
- *
- * `path` is what follows the REST mount point, so `/api/blog/posts/1` arrives as
- * `blog/posts/1`. A path this door does not serve returns `pass`, and that is what
- * lets an app keep its own `/api/*` handlers.
+ * Match the URL against the canonical table, invoke the call it names, shape the result for HTTP.
  */
 export async function serveRest(app: App, request: DoorRequest): Promise<Outcome> {
   // The app decides, not the host. A route file may exist and a middleware may be
@@ -123,7 +87,7 @@ export async function serveRest(app: App, request: DoorRequest): Promise<Outcome
     result = await invokeOn(
       app,
       { entity: route.entityName, op: route.operationName },
-      { params, query: request.query, body: request.body },
+      { params, query: request.query, input: request.body },
       undefined,
       request.state,
     );
@@ -135,13 +99,7 @@ export async function serveRest(app: App, request: DoorRequest): Promise<Outcome
   return shapeRest(route.operationName, result);
 }
 
-/**
- * What an operation's return becomes on the wire.
- *
- * Separate from `serveRest` because it is a DECISION and dispatch is not: it can be
- * pinned without a runner, and both hosts get it whether the call ran in memory or
- * came back over JSON-RPC.
- */
+/** What an operation's return becomes on the wire. */
 export function shapeRest(operationName: string, result: unknown): Outcome {
   if (result === null) return { kind: 'error', status: 404, body: { message: 'Not found' } };
 
@@ -168,13 +126,8 @@ type EntityClass = { name: string };
 type CallInput = Partial<InvocationContext>;
 
 /**
- * Name a call server-side and let the runner place it — local façade → direct
- * in-memory execution, a frond in `remotes` → JSON-RPC on the wire. The caller
- * never knows which.
- *
- * `state` is explicit here. Each host wraps this with its own way of finding the
- * current request (Nitro's async context, Next's `headers()` scope), because that
- * is the one part a host actually owns.
+ * Name a call server-side and let the runner place it — local façade → direct in-memory execution,
+ * a frond in `remotes` → JSON-RPC on the wire.
  */
 export async function invokeOn<T = unknown>(
   app: App,
@@ -186,6 +139,6 @@ export async function invokeOn<T = unknown>(
   const { call, invocation } = callValueOf(target, opOrInput, input);
   // An explicit `state` on the input wins over the request's — the caller who spells
   // it is answering for it, which is what makes a call outside any request possible.
-  const given = typeof opOrInput === 'string' ? input : opOrInput;
-  return (await createAppRunner(app)(call, { ...invocation, state: given?.state ?? state })) as T;
+  const explicit = typeof opOrInput === 'string' ? input : opOrInput;
+  return (await createAppRunner(app)(call, { ...invocation, state: explicit?.state ?? state })) as T;
 }

package/src/session.ts

@@ -1,11 +1,6 @@
 /**
- * The session view — the one place that turns the server-resolved
- * request context (filled by the auth middleware) into what the client
- * is allowed to see. One resolution, three readers: the page by
- * hydration, the refresh route over the wire, handlers by invocation.
- *
- * The app-declared context (viewer enrichment) will attach here when
- * a real case lands — this function is the seam.
+ * The session view — the one place that turns the server-resolved request context (filled by the
+ * auth middleware) into what the client is allowed to see.
  */
 
 export interface SessionView {

package/src/state.ts

@@ -1,14 +1,4 @@
-/**
- * Who the caller is, resolved server-side from the request's own headers.
- *
- * Nuxt answers this with a Nitro middleware that stamps `event.context`; a
- * Web-standard host has no such seam on a route handler, so it resolves here
- * instead. Same source (the auth runtime mounted on `app.auth`), same result shape
- * (`{ user, session }`), so `serveRpc` and `serveRest` cannot tell hosts apart.
- *
- * What must stay true in both: this is what the SERVER resolved. A browser sits
- * outside the topology, so nothing here may come from the payload.
- */
+/** Who the caller is, resolved server-side from the request's own headers. */
 import { useFougereApp } from './boot.js';
 
 type SessionApi = {

package/src/web.ts

@@ -1,16 +1,4 @@
-/**
- * The three doors as Web-standard handlers: `Request` in, `Response` out.
- *
- * This is the whole server surface for any host built on fetch semantics — Next
- * route handlers, TanStack Start server routes, Hono, a bare `Deno.serve`. Such a
- * host mounts these; it does not translate anything, because there is nothing left
- * to translate.
- *
- * Nuxt is the exception and keeps its own translation, for a reason worth stating:
- * an h3 event is not a `Request`, and reading its body has to straddle two h3
- * majors (`server/routes/call.post.ts` carries that hundred lines). That file is
- * what a NON-Web-standard host costs.
- */
+/** The three doors as Web-standard handlers: `Request` in, `Response` out. */
 import { serveRest, serveRpc, rpcParseError, useFougereApp, serveGraphQL } from './index.js';
 import { MAX_BODY_BYTES } from '@fougere/core';
 import { sessionViewOf } from './session.js';
@@ -18,11 +6,7 @@ import { stateFor } from './state.js';
 
 const WITH_BODY = new Set(['POST', 'PUT', 'PATCH']);
 
-/**
- * The call envelope. A named surface is the path segment after the door —
- * `/_fougere/call/public` serves the `public` audience — and `surfaceOf` reads it,
- * so a host only has to mount this at a path that keeps the segments.
- */
+/** The call envelope. */
 export async function fougereCall(request: Request): Promise<Response> {
   const declared = Number(request.headers.get('content-length'));
   if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
@@ -46,14 +30,7 @@ export async function fougereCall(request: Request): Promise<Response> {
   );
 }
 
-/**
- * The REST projection, mounted under `/api`.
- *
- * `pass` — a path this app does not serve — becomes a 404 here rather than a
- * fall-through, because a Web handler has nobody to fall through to. Hosts that
- * resolve a static route before a catch-all (Next does) still let an app keep its
- * own `/api/*` handlers: they are reached BEFORE this one, not after.
- */
+/** The REST projection, mounted under `/api`. */
 export async function fougereRest(request: Request): Promise<Response> {
   const app = await useFougereApp();
   const url = new URL(request.url);
@@ -81,12 +58,7 @@ export async function fougereSession(request: Request): Promise<Response> {
   return Response.json(sessionViewOf(await stateFor(request.headers)));
 }
 
-/**
- * GraphQL, at whatever path the host mounted it — `/graphql` by convention.
- *
- * Answers `404` when the app declares no GraphQL adapter, because unlike REST this
- * door is mounted at a path of its own: there is no app route underneath it to pass to.
- */
+/** GraphQL, at whatever path the host mounted it — `/graphql` by convention. */
 export async function fougereGraphQL(request: Request): Promise<Response> {
   const app = await useFougereApp();
   const body = (await request.json().catch(() => ({}))) as {