create-rindle 0.2.0 → 0.4.2

package/package.json

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

package/templates/minimal/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — working on __PROJECT_NAME__
+
+Guidance for coding agents (and new humans). This is a **Rindle** app — an
+incremental-view-maintenance (IVM) engine keeps every registered query's result
+exact on each write instead of re-running it. Three tiers: a TanStack Start SPA
+running the wasm engine in-process, an API authority, and the `rindled` daemon
+that owns the SQLite data. The correctness contract everywhere is
+**view-after-write == fresh-query**.
+
+Rindle docs are served as raw markdown for LLMs: index at
+<https://rindle.sh/llms.txt>, the whole app track in one file at
+<https://rindle.sh/llms-app.txt>.
+
+## Commands
+
+- `pnpm dev` — the only command you need: boots `rindled` (prebuilt binary from
+  `@rindle/cli`, no Rust toolchain), applies `migrations/*.sql`, regenerates
+  `shared/schema.gen.ts`, seeds, and starts Vite (the app + the `/api/rindle`
+  server routes). Re-applies/regenerates on every `migrations/` change.
+- `pnpm typecheck` — regenerates the route tree, then `tsc --noEmit`.
+- `pnpm migrate` / `pnpm seed` — one-shot apply / seed against the running daemon.
+
+## Rules that keep the app correct
+
+Break one of these and the app goes subtly wrong. Treat violations as bugs in
+review:
+
+1. **SQL is the source of truth.** Change the schema by **adding** a
+   `migrations/*.sql` file (additive DDL: `CREATE TABLE` / `ADD COLUMN` /
+   `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).
+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
+   server subscription.
+5. **The daemon token is server-only.** It gates the private control plane
+   (`:7600`) and must never reach the browser; the browser holds only the
+   lease-gated public WebSocket (`:7601`).
+6. **Subscribe to windows, not whole tables** — order + `limit`, and ratchet
+   `limit` up for "load more". The engine keeps the window (and any `countAs`)
+   exact as rows enter and leave.
+7. **Keep `*.queries.ts` modules React-free** — no `.tsx` imports. The browser,
+   the API authority, and the SSR loader all import these same modules.
+
+## File map
+
+| Path | What it is |
+| --- | --- |
+| `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 |
+| `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 |
+| `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 |
+
+## Reading more
+
+Per-page markdown mirrors live at `https://rindle.sh/docs/<slug>.md`. Most
+relevant here: `synced-app-quickstart`, `client`, `api-server`, `schema`,
+`fragments`, `supported-queries-ts`, `change-model`.

package/templates/minimal/migrations/0001_init.sql

@@ -12,10 +12,10 @@
 -- declared BOOLEAN/BOOL → boolean(), JSON → json(). Column ORDER matters — the IVM engine reads it
 -- back with PRAGMA table_info. `IF NOT EXISTS` keeps re-runs safe.
 
-CREATE TABLE IF NOT EXISTS room (id TEXT, name TEXT, createdAt REAL, PRIMARY KEY (id));
+CREATE TABLE IF NOT EXISTS room (id TEXT NOT NULL, name TEXT NOT NULL, createdAt REAL NOT NULL, PRIMARY KEY (id));
 -- The room list orders newest-first.
 CREATE INDEX IF NOT EXISTS room_created ON room (createdAt DESC, id);
 
-CREATE TABLE IF NOT EXISTS message (id TEXT, roomId TEXT, author TEXT, body TEXT, createdAt REAL, PRIMARY KEY (id));
+CREATE TABLE IF NOT EXISTS message (id TEXT NOT NULL, roomId TEXT NOT NULL, author TEXT NOT NULL, body TEXT NOT NULL, createdAt REAL NOT NULL, PRIMARY KEY (id));
 -- Forward (a room's messages, oldest-first) AND the reverse the live count uses when a message changes.
 CREATE INDEX IF NOT EXISTS message_room ON message (roomId, createdAt, id);

package/templates/minimal/shared/schema.gen.ts

@@ -4,7 +4,8 @@
 // Column kinds come from your declared SQL types: TEXT maps to string(), INTEGER/REAL to
 // number(), and a column declared BOOLEAN/BOOL or JSON to boolean()/json(). The only thing the
 // SQL can't carry is a refinement *within* a kind — the element type of json<T>(), or a
-// string/number literal union — so re-apply those few annotations after each regen.
+// string/number literal union — declare those ONCE in a hand-written module with
+// refineTable(...) + refineSchema(...); they survive every regen of this file.
 
 import { createSchema, number, string, table } from "@rindle/client";
 

package/templates/minimal/src/RindleApp.tsx

@@ -1,47 +1,19 @@
-// The SSR→SPA store handoff. Provides the Rindle store to the tree via `@rindle/react`, swapping the
-// backend under `useQuery` without changing a single component:
-//
-//   - Server render + browser HYDRATION: a transport-less seed Store, hydrated from the SSR snapshot.
-//     `useQuery` reads its seed, so the server and the client's first render produce identical markup
-//     with NO engine on either side.
-//   - After hydration: the wasm IVM engine boots (client-only dynamic import, rindle-client.ts), its
-//     views are seeded from the same snapshot (so the swap shows the SSR rows with no flash), and the
-//     live `subscribe` reconciles — the page is now a live SPA.
+// The SSR→SPA store handoff. The handoff itself — seed the render from the SSR snapshot, boot the
+// wasm engine after hydration, swap the store under `useQuery` with no flash — lives in `<RindleSSR>`
+// (@rindle/react). This file just binds THIS app's `schema` + `bootClient` into it, so the route
+// tree keeps rendering `<RindleApp ssrState={…}>` unchanged.
 
-import { useEffect, useRef, useState } from "react";
 import type { ReactNode } from "react";
-import { Rindle } from "@rindle/react";
-import { OneShotBackend, Store, type DehydratedState } from "@rindle/client";
+import { RindleSSR } from "@rindle/react";
+import type { DehydratedState } from "@rindle/client";
 
 import { schema } from "../shared/app-def.ts";
 import { bootClient } from "./rindle-client.ts";
 
-type RindleClient = Awaited<ReturnType<typeof bootClient>>;
-
 export function RindleApp({ ssrState, children }: { ssrState: DehydratedState; children: ReactNode }) {
-  // Built ONCE from the first-render snapshot. Backs the server render AND the matching client
-  // hydration pass — same seeds in, same markup out.
-  const [seedStore] = useState(() => {
-    const store = new Store(schema, new OneShotBackend());
-    store.hydrate(ssrState);
-    return store;
-  });
-
-  // The live wasm store — booted only in the browser, only after hydration.
-  const [liveStore, setLiveStore] = useState<RindleClient["store"] | null>(null);
-  const ssrStateRef = useRef(ssrState);
-  ssrStateRef.current = ssrState;
-  useEffect(() => {
-    let alive = true;
-    void bootClient().then((app) => {
-      if (!alive) return;
-      app.store.hydrate(ssrStateRef.current); // seed the live views so the swap doesn't flash empty
-      setLiveStore(app.store);
-    });
-    return () => {
-      alive = false;
-    };
-  }, []);
-
-  return <Rindle store={liveStore ?? seedStore}>{children}</Rindle>;
+  return (
+    <RindleSSR schema={schema} ssrState={ssrState} boot={bootClient}>
+      {children}
+    </RindleSSR>
+  );
 }

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

@@ -70,6 +70,10 @@ 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),
     onRejected: (envelope, reason) => rejectionHandler(envelope, reason),
   });
 }

package/templates/minimal/src/ssr.ts

@@ -36,16 +36,11 @@ const readInProcess: OneShotQueryFn = async ({ name, args }): Promise<OneShotRes
 };
 
 /** Preload the given NAMED queries through the authority and return the dehydrated first-paint cache to
- *  embed in the HTML. Call from a route loader (server only). A failed read degrades to no seed for
- *  that query (the live engine fills it in after hydration) rather than breaking the whole page. */
+ *  embed in the HTML. Call from a route loader (server only). `preloadAll` degrades a failed read to no
+ *  seed for that query (the live engine fills it in after hydration) rather than breaking the whole page. */
 export async function preloadRindle(queries: Array<Query<any, any, any>>): Promise<DehydratedState> {
-  const server = createServerStore(schema, { query: readInProcess });
-  await Promise.all(
-    queries.map((query) =>
-      server.preload(query).catch((err) => {
-        console.error("[ssr] preload failed; rendering this query without its first-paint seed:", err instanceof Error ? err.message : err);
-      }),
-    ),
-  );
-  return server.dehydrate();
+  return createServerStore(schema, { query: readInProcess }).preloadAll(queries, {
+    onError: (_query, err) =>
+      console.error("[ssr] preload failed; rendering this query without its first-paint seed:", err instanceof Error ? err.message : err),
+  });
 }