create-rindle 0.4.2 → 0.4.4

package/README.md

@@ -17,6 +17,11 @@ cd my-app
 pnpm dev
 ```
 
+Full docs — what the template contains and how to grow it:
+**[rindle.sh/docs/create-rindle](https://rindle.sh/docs/create-rindle)** · markdown
+mirror: [`create-rindle.md`](https://rindle.sh/docs/create-rindle.md) · for agents:
+[llms.txt](https://rindle.sh/llms.txt)
+
 ## What you get
 
 A minimal but real three-tier Rindle app (a tiny forum-of-rooms with **live message counts**):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-rindle",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/templates/minimal/AGENTS.md

@@ -30,15 +30,21 @@ review:
    `CREATE INDEX`; every table a single primary key). **Never hand-edit
    `shared/schema.gen.ts`** — it is generated from the live daemon and
    overwritten on the next migration.
-2. **Predicted mutators are deterministic and replayable**
-   (`shared/app-def.ts`): no `Date.now()`, no `Math.random()`, no I/O — they
-   re-run on every rebase. Generate ids and timestamps at the callsite and pass
-   them in as args.
-3. **Every mutator has two halves under one name**: the client's *predicted*
-   mutator in `shared/app-def.ts` and the server's *authoritative* SQL twin in
-   `server/app-api.ts`. Add or change them together. Only `(name, args)` ever
-   crosses the wire — validate args hard on the server; `throw` to hard-reject
-   (the optimistic write snaps back on its own; write no rollback code).
+2. **Mutators are one isomorphic body, deterministic and replayable**
+   (`shared/app-def.ts`): a generator that `yield`s logical ops
+   (`yield tx.insert(...)`), paired with its zod arg schema via
+   `shared(args, gen)`. No `Date.now()`, no `Math.random()`, no I/O — the client
+   re-invokes the body on every rebase. Generate ids and timestamps at the
+   callsite and pass them in as args; the acting user is `ctx.user` (injected
+   per tier), never an arg.
+3. **The server drives the same body** — `sharedApiMutators` in
+   `server/app-api.ts` auto-wraps the whole registry (parse the untrusted wire
+   args through each mutator's `.args`, inject the authenticated principal,
+   render every op to SQL). Add an explicit entry ONLY for server-only
+   authority the client must not predict (a policy guard, a raw `tx.exec`
+   relational gate). Only `(name, args)` ever crosses the wire; `throw` to
+   hard-reject (the optimistic write snaps back on its own; write no rollback
+   code).
 4. **Remote subscriptions must be named.** Define queries with `defineQuery` in
    `src/components/*.queries.ts` and register them in `server/app-api.ts`. An
    ad-hoc `store.query.…` builder resolves **locally only** — it never opens a
@@ -58,10 +64,10 @@ review:
 | --- | --- |
 | `migrations/*.sql` | the real schema — the only place DDL lives |
 | `shared/schema.gen.ts` | **generated** table schema — do not edit |
-| `shared/app-def.ts` | the shared contract: relationships, query builder, predicted mutators |
+| `shared/app-def.ts` | the shared contract: relationships, query builder, isomorphic mutators |
 | `src/components/*.queries.ts` | named queries + fragments, co-located with their components |
 | `src/rindle-client.ts` | the one-call browser wire-up (`createRindleClient`) |
-| `server/app-api.ts` | the authority: `registerQueries` + authoritative SQL mutators + policy |
+| `server/app-api.ts` | the authority: `registerQueries` + `sharedApiMutators` + server-only policy |
 | `src/routes/api.rindle.*.tsx` | TanStack Start server routes exposing the authority over HTTP |
 | `server/dev.ts` | dev orchestration (`rindle up` + seed + Vite) |
 | `src/ssr.ts` | SSR preload of the same named queries for first paint |

package/templates/minimal/README.md

@@ -11,8 +11,9 @@ Three tiers, same as the Rindle flagship examples:
 - **Browser** — a TanStack Start SPA whose data layer *is* Rindle. The wasm IVM engine runs
   in-process: reads resolve locally and instantly, writes apply optimistically and reconcile on
   confirmation. Views are co-located Relay-style fragments (`src/components/*.queries.ts`).
-- **API authority** (`server/app-api.ts`) — resolves named queries to ASTs, runs the authoritative SQL
-  mutators, and enforces policy: reads are public, writes require an identity, and a `"spam"` name/body
+- **API authority** (`server/app-api.ts`) — resolves named queries to ASTs, drives the **same
+  isomorphic mutators** the browser predicted (their logical ops rendered to SQL), and enforces
+  policy: reads are public, writes require an identity, and a `"spam"` name/body
   is rejected (you'll see the optimistic write snap back + a toast). It's host-agnostic: the browser
   reaches it through TanStack Start **server routes** (`src/routes/api.rindle.{query,read,mutate}.tsx`,
   via `server/rindle-http.ts`) that run in the same server as the app, and SSR calls the very same
@@ -60,10 +61,10 @@ of `vite build` and never ship to production.
 |---|---|
 | `migrations/*.sql` | the schema — **source of truth** |
 | `shared/schema.gen.ts` | generated `@rindle/client` schema (don't edit by hand) |
-| `shared/app-def.ts` | the contract root: schema re-export, relationships, mutators |
+| `shared/app-def.ts` | the contract root: schema re-export, relationships, isomorphic mutators |
 | `shared/auth.ts` | the identity seam (`AuthProvider`) |
 | `server/dev.ts` | one-command dev orchestrator |
-| `server/app-api.ts` | the authority: query resolution, SQL mutators, policy (host-agnostic) |
+| `server/app-api.ts` | the authority: query resolution, `sharedApiMutators`, policy (host-agnostic) |
 | `server/rindle-http.ts` | adapts the authority to a Web Request (the Start API routes call it) |
 | `src/routes/api.rindle.*.tsx` | the three API endpoints as Start server routes (the browser's API) |
 | `src/ssr.ts` | first-paint preload — calls the authority in-process |

package/templates/minimal/server/app-api.ts

@@ -1,19 +1,41 @@
 // The app authority, runtime-AGNOSTIC. The serverless-shaped tier's actual logic: it resolves named
-// queries to ASTs (the daemon mints opaque leases), runs the AUTHORITATIVE mutators into approved SQL,
-// enforces policy (identity required to write, a "spam" rejection demo), and talks to the daemon over
-// the private bearer-auth'd control plane.
+// queries to ASTs (the daemon mints opaque leases), drives the SAME isomorphic mutators the browser
+// predicted (shared/app-def.ts) with their ops rendered to approved SQL, enforces policy (identity
+// required to write, a "spam" rejection demo), and talks to the daemon over the private bearer-auth'd
+// control plane.
 //
 // It is deliberately free of any host: server/rindle-http.ts adapts it to a Web Request for the Start
 // API routes (src/routes/api.rindle.*.tsx) the browser calls, and the SSR loader (src/ssr.ts) calls the
 // SAME factory in-process. The only per-host inputs are the daemon's control-plane URL + token and the
 // AuthProvider.
 
-import { createRindleApiServer, defineApiMutators, registerQueries } from "@rindle/api-server";
-import type { ApiMutators, MutationContext, RindleApiServer, SqlMutationTx } from "@rindle/api-server";
+import {
+  createRindleApiServer,
+  defineApiMutators,
+  registerQueries,
+  runSharedMutation,
+  sharedApiMutators,
+} from "@rindle/api-server";
+import type {
+  ApiMutator,
+  ApiMutators,
+  MutationContext,
+  MutatorCtx,
+  RindleApiServer,
+  ServerMutationTx,
+  SharedMutatorWithArgs,
+} from "@rindle/api-server";
 import { HttpRindleDaemonClient } from "@rindle/daemon-client";
 import type { FetchLike } from "@rindle/daemon-client";
 
-import { createRoomArgs, normalizeBody, normalizeName, normalizeSubject, postMessageArgs } from "../shared/app-def.ts";
+import {
+  mutators as sharedMutators,
+  normalizeBody,
+  normalizeName,
+  normalizeSubject,
+  postMessageArgs,
+  schema,
+} from "../shared/app-def.ts";
 import type { Identity } from "../shared/auth.ts";
 import { roomsQuery } from "../src/components/RoomCard.queries.ts";
 import { roomDetailQuery } from "../src/components/RoomView.queries.ts";
@@ -26,23 +48,50 @@ export type User = Identity | undefined;
 // can't smuggle a garbage arg in.
 const apiQueries = registerQueries<User>([roomsQuery, roomDetailQuery]);
 
+// MUTATORS ARE ISOMORPHIC — defined once in shared/app-def.ts and auto-driven here by
+// `sharedApiMutators`: for each mutator it parses the untrusted wire args (the mutator's co-located
+// `.args` schema), injects the AUTHENTICATED principal as `ctx.user` (`sharedCtx` — never a client
+// arg), and drives the SAME body the client predicted, rendering every yielded op to SQL. A mutator
+// whose server run needs no authority beyond that triad needs no entry here at all.
+//
+// The ONLY explicit entries are server-only AUTHORITY the client must NOT predict, each OVERRIDING
+// its auto-wrapped default (spread first, override wins): the "spam" policy guard (so the demo's
+// rejection path stays exercised end to end) and postMessage's room-exists gate (relational SQL a
+// keyed op can't express — the raw `tx.exec` escape hatch).
+
+/** The `MutatorCtx` a shared body sees on the server: the AUTHENTICATED subject (throws if absent —
+ *  a business rejection). Never a client-supplied author. */
+function sharedCtx(ctx: MutationContext<User>): MutatorCtx {
+  return { user: requireUser(ctx.user).subject };
+}
+
+/** Layer a server-only arg policy onto a shared mutator (throw → hard reject), then drive the SAME
+ *  body the client predicts. */
+function withGuard<A>(gen: SharedMutatorWithArgs<A>, guard: (a: A) => void): ApiMutator<User, unknown> {
+  return (tx, raw, ctx) => {
+    const a = gen.args.parse(raw);
+    guard(a);
+    return runSharedMutation(gen, a, sharedCtx(ctx), tx);
+  };
+}
+
 const apiMutators = defineApiMutators<User, ApiMutators<User>>({
-  createRoom: (tx: SqlMutationTx, raw: unknown, ctx: MutationContext<User>) => {
-    const a = createRoomArgs.parse(raw);
-    requireUser(ctx.user);
-    const name = cleanName(a.name);
-    tx.exec("INSERT OR IGNORE INTO room (id, name, createdAt) VALUES (?, ?, ?)", [a.id, name, a.createdAt]);
-  },
-  postMessage: (tx: SqlMutationTx, raw: unknown, ctx: MutationContext<User>) => {
+  ...sharedApiMutators(sharedMutators, sharedCtx),
+
+  // (a) a server-only policy on the shared body: an empty or "spam" name throws BEFORE any write.
+  createRoom: withGuard(sharedMutators.createRoom, (a) => void cleanName(a.name)),
+
+  // (b) the raw-SQL escape hatch: insert only into a room that exists, so a racing client can't post
+  //     into a deleted room. The client predicts the plain shared insert and it snaps back if this
+  //     no-ops. `author` is the VERIFIED subject, never a wire arg.
+  postMessage: async (tx: ServerMutationTx, raw: unknown, ctx: MutationContext<User>) => {
     const a = postMessageArgs.parse(raw);
-    const who = requireUser(ctx.user);
+    const author = sharedCtx(ctx).user;
     const body = cleanBody(a.body);
-    // Insert only into a room that exists — a racing client can't post into a deleted room. `author`
-    // is the VERIFIED subject, never the wire arg.
     tx.exec(
       `INSERT INTO message (id, roomId, author, body, createdAt)
        SELECT ?, ?, ?, ?, ? WHERE EXISTS (SELECT 1 FROM room WHERE id = ?)`,
-      [a.id, a.roomId, who.subject, body, a.createdAt, a.roomId],
+      [a.id, a.roomId, author, body, a.createdAt, a.roomId],
     );
   },
 });
@@ -67,6 +116,7 @@ export function createAppApi(opts: AppApiOptions): RindleApiServer<User> {
   });
   return createRindleApiServer<User>({
     daemon,
+    schema, // drives the dialect-SQL renderer for the shared mutators' logical ops
     queries: apiQueries,
     mutators: apiMutators,
     authorizeQuery: () => true, // public reads

package/templates/minimal/shared/app-def.ts

@@ -1,16 +1,17 @@
 // The shared CONTRACT root: the normalized schema, the relationships the views join back over, the
-// normalization helpers, the mutator arg schemas, and the client's PREDICTED mutators. Both tiers
-// import it — the browser for everything, the API server for the schema + normalization + the
-// AUTHORITATIVE mutator twins (server/app-api.ts) with the same names.
+// normalization helpers, and the ISOMORPHIC mutators — one generator body per mutator, driven by
+// BOTH tiers. The browser drives each body synchronously (the optimistic prediction); the API server
+// drives the SAME body inside an authoritative transaction, rendering its ops to SQL
+// (server/app-api.ts).
 //
 // This module is the leaf of the contract DAG: it depends on nothing app-internal. The named root
 // queries AND the per-component SELECTIONS they compose are co-located with their components in
 // `src/components/*.queries.ts` (Relay-style co-location). Keeping the schema here, free of those
 // imports, is what keeps that graph acyclic.
 
-import { defineRelationships, newQueryBuilder, rel } from "@rindle/client";
-import type { Row } from "@rindle/client";
-import type { ClientRegistry, MutationTx } from "@rindle/optimistic";
+import { defineRelationships, newQueryBuilder, rel, shared } from "@rindle/client";
+import type { IsoTx, MutationGen, MutatorCtx, Row } from "@rindle/client";
+import type { ClientRegistry } from "@rindle/optimistic";
 import { z } from "zod";
 
 // The schema is GENERATED from migrations/*.sql into ./schema.gen.ts by `rindle schema gen` — `pnpm
@@ -57,10 +58,11 @@ export function normalizeSubject(raw: string): string {
 
 // --------------------------------------------------------------------------- mutator args
 //
-// One zod schema per mutator. The SERVER parses the UNTRUSTED wire args through it (server/app-api.ts);
-// BOTH tiers derive the arg TYPE from it (`z.infer`). `author` rides the args for the CLIENT's
-// prediction only — the server ALWAYS overrides it with the authenticated identity, so it is
-// unspoofable for the authoritative write.
+// One zod schema per mutator, co-located with its body via `shared(args, gen)`. The SERVER parses the
+// UNTRUSTED wire args through it (server/app-api.ts); BOTH tiers derive the arg TYPE from it
+// (`z.infer`). NB: the AUTHOR is NOT an arg — it is the acting principal (`ctx.user`), injected by
+// each tier's driver (the client's local handle for the prediction; the server's AUTHENTICATED
+// identity for the authoritative run), so it is unspoofable over the wire.
 
 export const createRoomArgs = z.object({ id: z.string(), name: z.string(), createdAt: z.number() });
 export type CreateRoomArgs = z.infer<typeof createRoomArgs>;
@@ -69,32 +71,36 @@ export const postMessageArgs = z.object({
   id: z.string(),
   roomId: z.string(),
   body: z.string(),
-  author: z.string(),
   createdAt: z.number(),
 });
 export type PostMessageArgs = z.infer<typeof postMessageArgs>;
 
-// --------------------------------------------------------------------------- mutators (PREDICTED)
+// --------------------------------------------------------------------------- mutators (ISOMORPHIC)
 //
-// Deterministic + replayable: every value that would otherwise come from the clock or a random source
-// is passed in args (ids, timestamps). The SQL twins in server/app-api.ts enforce the authoritative
-// policy (identity required, a "spam" rejection demo).
+// ONE body per mutator, shared by both tiers. Each is a GENERATOR: it `yield`s logical write ops
+// (`yield tx.insert(...)`) instead of touching a database, so the SAME function runs synchronously
+// against the browser's wasm engine (the optimistic prediction) AND asynchronously against a live
+// transaction on the server, each op rendered to SQL. Deterministic + replayable: every value that
+// would otherwise come from the clock or a random source is passed in args (ids, timestamps) — the
+// client RE-INVOKES the body on every rebase. Normalization runs INSIDE the body, so both tiers
+// normalize identically; the server layers its own policy on top (identity required, a "spam"
+// rejection demo, the room-exists guard — server/app-api.ts).
 
 export const mutators = {
-  createRoom: (tx: MutationTx, a: CreateRoomArgs) => {
+  createRoom: shared(createRoomArgs, function* (tx: IsoTx, a: CreateRoomArgs): MutationGen {
     const name = normalizeName(a.name);
-    if (!name) return;
-    tx.insert("room", { id: a.id, name, createdAt: a.createdAt });
-  },
-  postMessage: (tx: MutationTx, a: PostMessageArgs) => {
+    if (!name) return; // a no-op prediction is fine; the server's guard hard-rejects
+    yield tx.insertIgnore("room", { id: a.id, name, createdAt: a.createdAt });
+  }),
+  postMessage: shared(postMessageArgs, function* (tx: IsoTx, a: PostMessageArgs, ctx: MutatorCtx): MutationGen {
     const body = normalizeBody(a.body);
     if (!body) return;
-    tx.insert("message", {
+    yield tx.insert("message", {
       id: a.id,
       roomId: a.roomId,
-      author: normalizeSubject(a.author),
+      author: normalizeSubject(ctx.user),
       body,
       createdAt: a.createdAt,
     });
-  },
+  }),
 } satisfies ClientRegistry;

package/templates/minimal/src/components/Composer.tsx

@@ -5,7 +5,7 @@
 import { useState } from "react";
 import type { FormEvent } from "react";
 
-import { app, currentHandle } from "../rindle-client.ts";
+import { app } from "../rindle-client.ts";
 
 export function Composer({ roomId }: { roomId: string }) {
   const [body, setBody] = useState("");
@@ -15,11 +15,11 @@ export function Composer({ roomId }: { roomId: string }) {
     const text = body.trim();
     if (!text) return;
     const now = Date.now();
+    // The author is NOT an arg — it's the acting principal (ctx.user), injected by each tier.
     app.mutate.postMessage({
       id: `msg-${now}-${Math.random().toString(36).slice(2, 7)}`,
       roomId,
       body: text,
-      author: currentHandle(),
       createdAt: now,
     });
     setBody("");

package/templates/minimal/src/rindle-client.ts

@@ -11,7 +11,7 @@ import type { MutationEnvelope } from "@rindle/client";
 
 import wasmUrl from "rindle-wasm-bin?url";
 
-import { mutators, schema } from "../shared/app-def.ts";
+import { mutators, normalizeSubject, schema } from "../shared/app-def.ts";
 
 // The precise client type — including the typed `mutate.*` surface — is INFERRED from the concrete
 // `createRindleClient({ schema, mutators, … })` call in `bootClientInner`.
@@ -63,6 +63,9 @@ async function bootClientInner() {
   return createRindleClient({
     schema,
     mutators,
+    // The acting principal a mutator sees as ctx.user — the prediction's author. The server injects
+    // its OWN verified identity for the authoritative run (server/app-api.ts sharedCtx).
+    user: () => normalizeSubject(currentHandle()),
     api: {
       url: "", // same-origin: /api/rindle/* is a Start server route on this same server
       // Identity per request: the dev handle header. A real app sends a verified token instead.
@@ -70,10 +73,7 @@ async function bootClientInner() {
     },
     // 7601 = the daemon's PUBLIC ws port (7600 is the HTTP control plane).
     daemon: { wsUrl: import.meta.env.VITE_DAEMON_WS ?? "ws://127.0.0.1:7601" },
-    // `dev.resetOnMutationGap` postdates the published @rindle/optimistic (0.2.0); the spread-cast
-    // keeps this scaffold typechecking against the registry package — older clients ignore the key,
-    // newer ones honor it. Inline the option (and drop the cast) once a release includes it.
-    ...({ dev: { resetOnMutationGap: import.meta.env.DEV } } as object),
+    dev: { resetOnMutationGap: import.meta.env.DEV },
     onRejected: (envelope, reason) => rejectionHandler(envelope, reason),
   });
 }