create-rindle 0.5.0 → 0.6.4

package/index.mjs

@@ -116,7 +116,7 @@ async function main() {
       (opts.install ? "" : `    ${pm} install\n`) +
       `    ${run} dev\n\n` +
       `  The migrations in migrations/*.sql are the source of truth — \`${run} dev\` applies them,\n` +
-      `  generates shared/schema.gen.ts, and boots the daemon + Vite (app + /api/rindle routes).\n` +
+      `  generates shared/schema.gen.ts, and boots the topology pair + Vite (app + /api/rindle routes).\n` +
       `  Open two browser windows, create a room, and watch writes sync live.\n\n`,
   );
 }

package/package.json

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

package/templates/minimal/AGENTS.md

@@ -3,9 +3,10 @@
 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**.
+running the wasm engine in-process, an API authority, and the data tier — the one
+topology (design 214): a `rindle-replicator` write-master + a `rindled`
+read-follower (`followers = 1` = the colocated pair). 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
@@ -13,18 +14,22 @@ Rindle docs are served as raw markdown for LLMs: index at
 
 ## Commands
 
-- `pnpm dev` — the one command: `concurrently` runs two processes — **daemon**
-  (`rindle up` supervising `rindled`, a prebuilt binary from `@rindle/cli`, no
-  Rust toolchain) applies `migrations/*.sql` and regenerates
-  `shared/schema.gen.ts` (re-running both on every `migrations/` change), and
-  **web** (`vite dev` on :3000) serves the app + the `/api/rindle/*` server
-  routes. Run either alone with `pnpm daemon` / `pnpm dev:web`.
+- `pnpm dev` — the one command: `concurrently` runs two processes — **fleet**
+  (`rindle up` renders `rindle.ncl` and supervises the pair — the
+  `rindle-replicator` write-master + the `rindled` follower, prebuilt binaries
+  from `@rindle/cli`, no Rust toolchain) applies `migrations/*.sql` to the master
+  and regenerates `shared/schema.gen.ts` from the follower (re-running both on
+  every `migrations/` change), and **web** (`rindle exec -- vite dev` on :3000) receives bindings
+  derived from `rindle.ncl` and serves the app +
+  the `/api/rindle/*` server routes. Run either alone with `pnpm fleet` /
+  `pnpm dev:web`.
 - `pnpm typecheck` — regenerates the route tree, then `tsc --noEmit`.
-- `pnpm migrate` — one-shot `rindle migrate apply` against the running daemon
-  (the dev loop already applies on boot + on every `migrations/` change).
-- `pnpm rindle:deploy` / `pnpm rindle:migrate:remote` — deploy the daemon tier to
-  Rindle Cloud (reads `topology.ncl`; run `rindle login` once first) and push
-  `migrations/*.sql` to it. Local dev never reads `topology.ncl`.
+- `pnpm migrate` — one-shot `rindle exec -- rindle migrate apply` against the write-master derived
+  from `rindle.ncl` (the follower's `/migrate` is write-fenced). The dev loop already
+  applies on boot + on every `migrations/` change.
+- `pnpm rindle:deploy` / `pnpm rindle:migrate:remote` — deploy the data tier to
+  Rindle Cloud (reads `rindle.ncl`, the same file `rindle up` runs locally; run
+  `rindle login` once first) and push `migrations/*.sql` to the deployed master.
 
 ## Rules that keep the app correct
 
@@ -55,9 +60,9 @@ review:
    `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`).
+5. **Daemon tokens are server-only.** They gate the follower and write-master control planes and
+   must never reach the browser; the browser reaches only the lease-gated fleet edge. Local endpoint
+   bindings come from `rindle exec`; never copy topology ports into package scripts.
 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.
@@ -75,8 +80,7 @@ review:
 | `src/rindle-client.ts` | the one-call browser wire-up (`createRindleClient`) |
 | `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 |
-| `daemon.json` | local `rindled` config `rindle up` reads (loopback, no auth token in dev) |
-| `topology.ncl` | Rindle Cloud deploy topology (`rindle deploy`) — not used by local dev |
+| `rindle.ncl` | the one topology (the colocated pair) — `rindle up` runs it locally, `rindle deploy` provisions it |
 | `src/ssr.ts` | SSR preload of the same named queries for first paint |
 
 ## Reading more

package/templates/minimal/README.md

@@ -18,7 +18,10 @@ Three tiers, same as the Rindle flagship examples:
   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
   factory **in-process** (no network hop).
-- **Daemon** (`rindled`) — owns the SQLite data + live IVM and streams normalized deltas to subscribers.
+- **Data tier** — the one topology (design 214): a `rindle-replicator` **write-master** plus a
+  `rindled` **read-follower** that owns the live IVM and streams normalized deltas to subscribers.
+  Writes land on the master; the follower serves reads. `followers = 1` is the *colocated pair* —
+  both processes on one box, the smallest shape.
 
 ## SQL is the source of truth
 
@@ -38,15 +41,18 @@ pnpm dev
 `pnpm dev` runs two processes with [`concurrently`](https://www.npmjs.com/package/concurrently) —
 the standard TanStack Start dev shape:
 
-- **`daemon`** — `rindle up` supervises `rindled` (prebuilt binaries from `@rindle/cli`, no Rust
-  toolchain needed) against the committed `daemon.json`, applies the migrations, and regenerates
-  `shared/schema.gen.ts` — re-running both on every `migrations/*.sql` change (`--watch`).
-- **`web`** — `vite dev` on <http://localhost:3000>, which serves both the app and the
-  `/api/rindle/*` Start server routes.
+- **`fleet`** — `rindle up` renders `rindle.ncl` and supervises the whole pair (the
+  `rindle-replicator` write-master + the `rindled` follower — prebuilt binaries from `@rindle/cli`,
+  no Rust toolchain needed), applies the migrations to the master, and regenerates
+  `shared/schema.gen.ts` from the follower's schema — re-running both on every `migrations/*.sql`
+  change (`--watch`).
+- **`web`** — `rindle exec -- vite dev` on <http://localhost:3000>, which serves both the app and the
+  `/api/rindle/*` Start server routes. `rindle exec` derives the stable fleet-edge read/ws binding
+  and write-master binding from `rindle.ncl`; no endpoint is copied into the package scripts.
 
-You can run either alone: `pnpm daemon` / `pnpm dev:web`. The local daemon binds to loopback and runs
-without an auth token; a real deployment sets one (`authToken` in the daemon config + a verified
-`RINDLE_DAEMON_TOKEN` on the server), which never reaches the browser.
+You can run either alone: `pnpm fleet` / `pnpm dev:web`. Both processes bind to loopback and run
+without an auth token in dev; a real deployment sets tokens (`RINDLE_DAEMON_TOKEN` for reads,
+`RINDLE_REPLICATOR_TOKEN` for writes on the server) that never reach the browser.
 
 Open two browser windows to watch writes sync live: create a room, post a message, and watch the
 room's count update on the home page with no polling. Try a room name or message containing "spam" to
@@ -57,20 +63,24 @@ see the rejection path (the optimistic write snaps back + a toast).
 
 ## Deploy
 
-Local dev runs the daemon on your machine (`daemon.json`). To run the **data tier** on Rindle Cloud,
-`topology.ncl` describes the managed app:
+`rindle.ncl` describes the **one topology** — the same file `rindle up` runs locally. To run the
+**data tier** on Rindle Cloud:
 
 ```bash
 rindle login                  # once — authenticate to Rindle Cloud
-pnpm rindle:deploy            # provision / re-attach the managed rindled (writes .rindle/cloud.json)
-pnpm rindle:migrate:remote    # push migrations/*.sql to the deployed daemon
+pnpm rindle:deploy            # provision / re-attach the managed app (writes .rindle/cloud.json)
+pnpm rindle:migrate:remote    # push migrations/*.sql to the deployed write-master
 ```
 
-`rindle deploy` reads `topology.ncl` and records the binding in `.rindle/cloud.json` — commit it, so
-future deploys re-attach to the same app. That deploys the **daemon** only; the **web app** (this
-Vite/TanStack Start app) deploys to any Node host — point its `RINDLE_DAEMON_URL` +
-`RINDLE_DAEMON_TOKEN` (server) and `VITE_DAEMON_WS` (browser) at the deployed daemon. Local dev is
-unaffected: bare `rindle up` ignores `topology.ncl` and uses `daemon.json`.
+`rindle deploy` reads `rindle.ncl` and records the binding in `.rindle/cloud.json` — commit it, so
+future deploys re-attach to the same app. `followers = 1` provisions a backed-up write-master + one
+follower (`replicated`, scales 1→N in place); raise it for more read replicas (`read-scaled`);
+`localRetention = true` provisions the one-box colocated pair (`colocated`, no streaming backup —
+no durability beyond the box). That deploys the **data tier**; the
+**web app** (this Vite/TanStack Start app) deploys to any Node host — point its `RINDLE_DAEMON_URL`
+(fleet-edge reads) + `RINDLE_REPLICATOR_URL` (writes) + their tokens (server) at the deployed data
+tier, and set `VITE_FLEET_WS` to the stable public fleet ws. These bindings are identical for one or
+many followers, and follower affinity is always enabled.
 
 ## Devtools
 
@@ -89,8 +99,7 @@ of `vite build` and never ship to production.
 | `shared/schema.gen.ts` | generated `@rindle/client` schema (don't edit by hand) |
 | `shared/app-def.ts` | the contract root: schema re-export, relationships, isomorphic mutators |
 | `shared/auth.ts` | the identity seam (`AuthProvider`) |
-| `daemon.json` | the local `rindled` config (`rindle up` reads it) — loopback, no auth token in dev |
-| `topology.ncl` | Rindle Cloud deploy topology (`rindle deploy`) — **not** used by local dev |
+| `rindle.ncl` | the one topology (the colocated pair) — `rindle up` runs it locally, `rindle deploy` provisions it |
 | `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) |

package/templates/minimal/package.json

@@ -8,13 +8,13 @@
     "node": ">=22.18"
   },
   "scripts": {
-    "daemon": "rindle up --config daemon.json --migrate --gen shared/schema.gen.ts --watch --dir migrations",
-    "dev:web": "vite dev --port 3000",
-    "dev": "concurrently -k -n daemon,web -c blue,green \"rindle up --config daemon.json --migrate --gen shared/schema.gen.ts --watch --dir migrations\" \"vite dev --port 3000\"",
+    "fleet": "rindle up --migrate --gen shared/schema.gen.ts --watch --dir migrations",
+    "dev:web": "rindle exec -- vite dev --port 3000",
+    "dev": "concurrently -k -n fleet,web -c blue,green \"pnpm fleet\" \"pnpm dev:web\"",
     "generate-routes": "tsr generate",
     "build": "vite build",
     "preview": "vite preview",
-    "migrate": "rindle migrate apply --dir migrations",
+    "migrate": "rindle exec -- rindle migrate apply --dir migrations",
     "rindle:deploy": "rindle deploy",
     "rindle:migrate:remote": "rindle migrate apply --remote",
     "typecheck": "tsr generate && tsc --noEmit"

package/templates/minimal/rindle.ncl

@@ -0,0 +1,28 @@
+# The Rindle topology for this app — the ONE topology (design 214): a `rindle-replicator`
+# write-master + one `rindled` read-follower. `followers = 1` is the colocated pair, the smallest
+# shape; raise it for more read replicas.
+#
+# A topology is a plain record of inputs; `rindle up` (local) and `rindle deploy` / `rindle render`
+# (cloud) merge it onto the topology library embedded in the `rindle` binary — nothing to import
+# or install. LOCAL dev reads THIS file: `rindle up` renders it and supervises the pair (see
+# package.json `dev` / `fleet`). The same file drives the cloud:
+#
+#   rindle login                  # once — authenticate to Rindle Cloud
+#   rindle deploy                 # provision / re-attach the managed app (writes .rindle/cloud.json)
+#   rindle migrate apply --remote # push migrations/*.sql to the deployed write-master
+#
+# `app` becomes the cloud display name and groups every component under one app in `rindle ps`.
+# `followers = 1` maps to the cloud `replicated` rung (a separate write-master + one follower,
+# backed up; scales 1→N in place); `followers > 1` maps to `read-scaled`. `localRetention = true`
+# maps to `colocated` (one box, both processes, no streaming backup).
+#
+# Every follower count renders a local fleet edge (the Fly-edge stand-in;
+# FOLLOWER-AFFINITY-DESIGN.md §10). `rindle exec` derives the app's read/write/ws bindings from this
+# file, so changing `followers = 1` to a wider fleet requires no application configuration change.
+# Set `RINDLE_DEV_CLIENT_REGION=A` to simulate a client region; the edge always mints an affinity
+# placement ticket, with a fleet of one resolving trivially to its only follower.
+{
+  profile = "replicated",
+  app = "__PROJECT_NAME__",
+  followers = 1,
+}

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

@@ -16,6 +16,7 @@ import {
   runSharedMutation,
   scoped,
   sharedApiMutators,
+  SplitDaemonClient,
 } from "@rindle/api-server";
 import type {
   ApiMutator,
@@ -112,10 +113,15 @@ const apiMutators = defineApiMutators<User, ApiMutators<User>>({
 
 /** A bearer-auth'd daemon control-plane target. */
 export interface AppApiOptions {
-  /** The daemon control-plane base URL — bearer-auth'd. */
+  /** The follower/read daemon control-plane base URL — bearer-auth'd. */
   daemonUrl: string;
   /** The shared bearer token for {@link daemonUrl} (daemon ↔ this tier ONLY — never reaches the browser). */
   daemonToken: string;
+  /** The required write-master (`rindle-replicator`) control-plane base URL. Writes + mutation
+   *  sessions go here; reads stay on {@link daemonUrl}. */
+  replicatorUrl: string;
+  /** Bearer for {@link replicatorUrl}, if it gates its write plane. */
+  replicatorToken?: string;
   /** Override the daemon HTTP transport (defaults to global `fetch`). */
   fetch?: FetchLike;
 }
@@ -123,13 +129,20 @@ export interface AppApiOptions {
 /** Build the configured API server. Stateless: safe to construct per-request or once per process.
  *  Reads are PUBLIC; writes require a verified identity. */
 export function createAppApi(opts: AppApiOptions): RindleApiServer<User> {
-  const daemon = new HttpRindleDaemonClient({
+  const reads = new HttpRindleDaemonClient({
     baseUrl: opts.daemonUrl,
     headers: { authorization: `Bearer ${opts.daemonToken}` },
     fetch: opts.fetch,
   });
   return createRindleApiServer<User>({
-    daemon,
+    daemon: new SplitDaemonClient(
+      new HttpRindleDaemonClient({
+        baseUrl: opts.replicatorUrl,
+        headers: opts.replicatorToken ? { authorization: `Bearer ${opts.replicatorToken}` } : undefined,
+        fetch: opts.fetch,
+      }),
+      reads,
+    ),
     schema, // drives the dialect-SQL renderer for the shared mutators' logical ops
     queries: apiQueries,
     mutators: apiMutators,
@@ -142,10 +155,16 @@ export function createAppApi(opts: AppApiOptions): RindleApiServer<User> {
 export function resolveDaemon(
   env: Record<string, string | undefined>,
   defaults: { daemonUrl: string; daemonToken: string },
-): Pick<AppApiOptions, "daemonUrl" | "daemonToken"> {
+): Pick<AppApiOptions, "daemonUrl" | "daemonToken" | "replicatorUrl" | "replicatorToken"> {
+  const replicatorUrl = env.RINDLE_REPLICATOR_URL;
+  if (!replicatorUrl) {
+    throw new Error("RINDLE_REPLICATOR_URL is required: writes must target the replicator write-master");
+  }
   return {
     daemonUrl: env.RINDLE_DAEMON_URL ?? defaults.daemonUrl,
     daemonToken: env.RINDLE_DAEMON_TOKEN ?? defaults.daemonToken,
+    replicatorUrl,
+    replicatorToken: env.RINDLE_REPLICATOR_TOKEN,
   };
 }
 

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

@@ -60,6 +60,11 @@ async function bootClientInner() {
     import("@rindle/wasm"),
   ]);
   await initWasm(wasmUrl);
+  // Every deployment exposes one stable fleet ws, including a fleet of one. `rindle exec` derives
+  // VITE_FLEET_WS from rindle.ncl, so increasing `followers` never changes app configuration.
+  // VITE_DAEMON_WS is a temporary direct-follower escape hatch for focused harnesses.
+  const directWs = import.meta.env.VITE_DAEMON_WS?.trim();
+  const fleetWs = import.meta.env.VITE_FLEET_WS?.trim() ?? "ws://127.0.0.1:7650";
   return createRindleClient({
     schema,
     mutators,
@@ -71,8 +76,8 @@ async function bootClientInner() {
       // Identity per request: the dev handle header. A real app sends a verified token instead.
       headers: (): Record<string, string> => ({ "x-rindle-user": currentHandle() }),
     },
-    // 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" },
+    // Normal app traffic always enters through the fleet edge. Direct follower access is explicit.
+    daemon: directWs ? { wsUrl: directWs } : { wsUrl: fleetWs, affinity: true },
     dev: { resetOnMutationGap: import.meta.env.DEV },
     onRejected: (envelope, reason) => rejectionHandler(envelope, reason),
   });

package/templates/minimal/vite-env.d.ts

@@ -6,9 +6,10 @@ declare module "rindle-wasm-bin?url" {
 }
 
 interface ImportMetaEnv {
-  /** The daemon's PUBLIC subscription ws. Unset in dev (rindle-client.ts falls back to
-   *  ws://127.0.0.1:7601); set it per deploy to point the browser at your daemon host. */
+  /** Deprecated direct-follower test/debug escape hatch. Normal apps use VITE_FLEET_WS. */
   readonly VITE_DAEMON_WS?: string;
+  /** Stable fleet-edge PUBLIC ws, derived by `rindle exec` for one or many followers. */
+  readonly VITE_FLEET_WS?: string;
 }
 
 interface ImportMeta {

package/templates/minimal/vite.config.ts

@@ -27,7 +27,7 @@ export default defineConfig({
   // client-only dynamic import in src/rindle-client.ts, so it never loads in the shell pass).
   ssr: { noExternal: [/^@rindle\//] },
   // No `server.proxy`: /api/rindle/* are Start server routes (src/routes/api.rindle.*.tsx) served by
-  // this same dev server. The daemon ws is still connected to directly (ws://127.0.0.1:7601).
+  // this same dev server. Browser subscriptions enter through the fleet edge derived by `rindle exec`.
   plugins: [
     // If you add TanStack's devtools panel, DISABLE console piping. The piping cross-forwards console
     // between the SSR server and the browser; a repeated log (a React warning, a Rindle fetch-retry)

package/templates/minimal/daemon.json

@@ -1,8 +0,0 @@
-{
-  "bindHost": "127.0.0.1",
-  "db": "rindle.db",
-  "httpPort": 7600,
-  "wsPort": 7601,
-  "nWorkers": 4,
-  "tables": []
-}

package/templates/minimal/topology.ncl

@@ -1,19 +0,0 @@
-# Rindle Cloud topology for this app — one write-owning `rindled` (the `dev` profile / Shape A).
-#
-# A topology is a plain record of inputs; `rindle deploy` (and `rindle render`) merge it onto the
-# `rindle.ncl` library embedded in the `rindle` binary — nothing to import or install. LOCAL dev does
-# NOT read this file: bare `rindle up` runs off `daemon.json` (see package.json `dev` / `daemon`).
-# This is what the CLOUD tooling reads:
-#
-#   rindle login                  # once — authenticate to Rindle Cloud
-#   rindle deploy                 # provision / re-attach the managed app (writes .rindle/cloud.json)
-#   rindle migrate apply --remote # push migrations/*.sql to the deployed daemon
-#
-# `app` becomes the cloud display name and groups every component under one app in `rindle ps`.
-# `dev` maps to the cloud `single` profile: one standalone daemon.
-{
-  profile = "dev",
-  app = "__PROJECT_NAME__",
-  daemonHttpPort = 7600,
-  daemonWsPort = 7601,
-}