create-rindle 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# AGENTS.md — working on __PROJECT_NAME__
|
|
2
|
+
|
|
3
|
+
Guidance for coding agents (and new humans). This is a **Rindle** app — an
|
|
4
|
+
incremental-view-maintenance (IVM) engine keeps every registered query's result
|
|
5
|
+
exact on each write instead of re-running it. Three tiers: a TanStack Start SPA
|
|
6
|
+
running the wasm engine in-process, an API authority, and the `rindled` daemon
|
|
7
|
+
that owns the SQLite data. The correctness contract everywhere is
|
|
8
|
+
**view-after-write == fresh-query**.
|
|
9
|
+
|
|
10
|
+
Rindle docs are served as raw markdown for LLMs: index at
|
|
11
|
+
<https://rindle.sh/llms.txt>, the whole app track in one file at
|
|
12
|
+
<https://rindle.sh/llms-app.txt>.
|
|
13
|
+
|
|
14
|
+
## Commands
|
|
15
|
+
|
|
16
|
+
- `pnpm dev` — the only command you need: boots `rindled` (prebuilt binary from
|
|
17
|
+
`@rindle/cli`, no Rust toolchain), applies `migrations/*.sql`, regenerates
|
|
18
|
+
`shared/schema.gen.ts`, seeds, and starts Vite (the app + the `/api/rindle`
|
|
19
|
+
server routes). Re-applies/regenerates on every `migrations/` change.
|
|
20
|
+
- `pnpm typecheck` — regenerates the route tree, then `tsc --noEmit`.
|
|
21
|
+
- `pnpm migrate` / `pnpm seed` — one-shot apply / seed against the running daemon.
|
|
22
|
+
|
|
23
|
+
## Rules that keep the app correct
|
|
24
|
+
|
|
25
|
+
Break one of these and the app goes subtly wrong. Treat violations as bugs in
|
|
26
|
+
review:
|
|
27
|
+
|
|
28
|
+
1. **SQL is the source of truth.** Change the schema by **adding** a
|
|
29
|
+
`migrations/*.sql` file (additive DDL: `CREATE TABLE` / `ADD COLUMN` /
|
|
30
|
+
`CREATE INDEX`; every table a single primary key). **Never hand-edit
|
|
31
|
+
`shared/schema.gen.ts`** — it is generated from the live daemon and
|
|
32
|
+
overwritten on the next migration.
|
|
33
|
+
2. **Predicted mutators are deterministic and replayable**
|
|
34
|
+
(`shared/app-def.ts`): no `Date.now()`, no `Math.random()`, no I/O — they
|
|
35
|
+
re-run on every rebase. Generate ids and timestamps at the callsite and pass
|
|
36
|
+
them in as args.
|
|
37
|
+
3. **Every mutator has two halves under one name**: the client's *predicted*
|
|
38
|
+
mutator in `shared/app-def.ts` and the server's *authoritative* SQL twin in
|
|
39
|
+
`server/app-api.ts`. Add or change them together. Only `(name, args)` ever
|
|
40
|
+
crosses the wire — validate args hard on the server; `throw` to hard-reject
|
|
41
|
+
(the optimistic write snaps back on its own; write no rollback code).
|
|
42
|
+
4. **Remote subscriptions must be named.** Define queries with `defineQuery` in
|
|
43
|
+
`src/components/*.queries.ts` and register them in `server/app-api.ts`. An
|
|
44
|
+
ad-hoc `store.query.…` builder resolves **locally only** — it never opens a
|
|
45
|
+
server subscription.
|
|
46
|
+
5. **The daemon token is server-only.** It gates the private control plane
|
|
47
|
+
(`:7600`) and must never reach the browser; the browser holds only the
|
|
48
|
+
lease-gated public WebSocket (`:7601`).
|
|
49
|
+
6. **Subscribe to windows, not whole tables** — order + `limit`, and ratchet
|
|
50
|
+
`limit` up for "load more". The engine keeps the window (and any `countAs`)
|
|
51
|
+
exact as rows enter and leave.
|
|
52
|
+
7. **Keep `*.queries.ts` modules React-free** — no `.tsx` imports. The browser,
|
|
53
|
+
the API authority, and the SSR loader all import these same modules.
|
|
54
|
+
|
|
55
|
+
## File map
|
|
56
|
+
|
|
57
|
+
| Path | What it is |
|
|
58
|
+
| --- | --- |
|
|
59
|
+
| `migrations/*.sql` | the real schema — the only place DDL lives |
|
|
60
|
+
| `shared/schema.gen.ts` | **generated** table schema — do not edit |
|
|
61
|
+
| `shared/app-def.ts` | the shared contract: relationships, query builder, predicted mutators |
|
|
62
|
+
| `src/components/*.queries.ts` | named queries + fragments, co-located with their components |
|
|
63
|
+
| `src/rindle-client.ts` | the one-call browser wire-up (`createRindleClient`) |
|
|
64
|
+
| `server/app-api.ts` | the authority: `registerQueries` + authoritative SQL mutators + policy |
|
|
65
|
+
| `src/routes/api.rindle.*.tsx` | TanStack Start server routes exposing the authority over HTTP |
|
|
66
|
+
| `server/dev.ts` | dev orchestration (`rindle up` + seed + Vite) |
|
|
67
|
+
| `src/ssr.ts` | SSR preload of the same named queries for first paint |
|
|
68
|
+
|
|
69
|
+
## Reading more
|
|
70
|
+
|
|
71
|
+
Per-page markdown mirrors live at `https://rindle.sh/docs/<slug>.md`. Most
|
|
72
|
+
relevant here: `synced-app-quickstart`, `client`, `api-server`, `schema`,
|
|
73
|
+
`fragments`, `supported-queries-ts`, `change-model`.
|
|
@@ -70,6 +70,10 @@ async function bootClientInner() {
|
|
|
70
70
|
},
|
|
71
71
|
// 7601 = the daemon's PUBLIC ws port (7600 is the HTTP control plane).
|
|
72
72
|
daemon: { wsUrl: import.meta.env.VITE_DAEMON_WS ?? "ws://127.0.0.1:7601" },
|
|
73
|
+
// `dev.resetOnMutationGap` postdates the published @rindle/optimistic (0.2.0); the spread-cast
|
|
74
|
+
// keeps this scaffold typechecking against the registry package — older clients ignore the key,
|
|
75
|
+
// newer ones honor it. Inline the option (and drop the cast) once a release includes it.
|
|
76
|
+
...({ dev: { resetOnMutationGap: import.meta.env.DEV } } as object),
|
|
73
77
|
onRejected: (envelope, reason) => rejectionHandler(envelope, reason),
|
|
74
78
|
});
|
|
75
79
|
}
|