@lunora/cli 1.0.0-alpha.104 → 1.0.0-alpha.106

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.
Files changed (8) hide show
  1. package/package.json +11 -11
  2. package/skills/README.md +28 -14
  3. package/skills/lunora/SKILL.md +48 -9
  4. package/skills/lunora-functions/SKILL.md +38 -3
  5. package/skills/lunora-migration-helper/SKILL.md +36 -17
  6. package/skills/lunora-performance-audit/SKILL.md +36 -6
  7. package/skills/lunora-quickstart/SKILL.md +61 -20
  8. package/skills/lunora-realtime/SKILL.md +43 -30
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lunora/cli",
3
- "version": "1.0.0-alpha.104",
3
+ "version": "1.0.0-alpha.106",
4
4
  "description": "The Lunora CLI: init, dev, deploy, codegen, run, reset, and migrate commands",
5
5
  "keywords": [
6
6
  "agent-skills",
@@ -51,28 +51,28 @@
51
51
  "access": "public"
52
52
  },
53
53
  "dependencies": {
54
- "@bomb.sh/tab": "0.0.19",
54
+ "@bomb.sh/tab": "0.0.21",
55
55
  "@lunora/bindings": "1.0.0-alpha.11",
56
- "@lunora/codegen": "1.0.0-alpha.57",
57
- "@lunora/config": "1.0.0-alpha.83",
56
+ "@lunora/codegen": "1.0.0-alpha.59",
57
+ "@lunora/config": "1.0.0-alpha.85",
58
58
  "@lunora/container": "1.0.0-alpha.16",
59
59
  "@lunora/d1": "1.0.0-alpha.43",
60
60
  "@lunora/errors": "1.0.0-alpha.8",
61
61
  "@lunora/runtime": "1.0.0-alpha.39",
62
- "@lunora/seed": "1.0.0-alpha.32",
62
+ "@lunora/seed": "1.0.0-alpha.34",
63
63
  "@visulima/cerebro": "3.0.0",
64
64
  "@visulima/error": "6.0.0",
65
- "@visulima/fs": "5.0.4",
66
- "@visulima/package": "5.0.4",
65
+ "@visulima/fs": "5.0.5",
66
+ "@visulima/package": "5.0.5",
67
67
  "@visulima/pail": "4.0.0",
68
68
  "@visulima/path": "3.0.0",
69
69
  "@visulima/spinner": "1.0.0",
70
- "@visulima/tui": "1.0.4",
70
+ "@visulima/tui": "1.0.5",
71
71
  "cfonts": "^3.3.1",
72
- "giget": "3.3.0",
72
+ "giget": "3.3.1",
73
73
  "jsonc-parser": "^3.3.1",
74
- "magic-string": "^1.0.0",
75
- "react": "^19.2.7",
74
+ "magic-string": "^1.1.0",
75
+ "react": "^19.2.8",
76
76
  "react-reconciler": "^0.33.0",
77
77
  "ts-morph": "^28.0.0"
78
78
  },
package/skills/README.md CHANGED
@@ -9,21 +9,35 @@ framework correctly. They ship inside `@lunora/cli` and are discovered by the
9
9
  Each skill is a `SKILL.md` with YAML frontmatter (`name`, `description`) in its
10
10
  own directory:
11
11
 
12
- | Skill | Use for |
13
- | -------------------------- | --------------------------------------------------------------------------- |
14
- | `lunora` | Router — start here, then switch to the matching skill below. |
15
- | `lunora-quickstart` | `lunora init` / adding Lunora to an app + first round-trip. |
16
- | `lunora-functions` | Core authoring rules — schema, validators, query/mutation/action, `ctx.db`. |
17
- | `lunora-realtime` | Client reactivity — live hooks, optimistic updates, `@lunora/db`. |
18
- | `lunora-setup-auth` | Authentication via `lunora registry add auth` (+ providers). |
19
- | `lunora-setup-mail` | Transactional email via `lunora registry add mail` — `sendEmail` actions. |
20
- | `lunora-setup-storage` | R2 file storage via `lunora registry add storage` — signed upload/download. |
21
- | `lunora-setup-scheduler` | Deferred (`ctx.scheduler`) + cron jobs (`lunora registry add crons`). |
22
- | `lunora-create-package` | Building a reusable registry item or `@lunora/*` package. |
23
- | `lunora-migration-helper` | Schema/data migrations, `.global()` D1 flow, the drift gate. |
24
- | `lunora-deploy` | Deploying to Cloudflare — wrangler bindings, secrets, the gate. |
25
- | `lunora-performance-audit` | Scans, indexes, OCC write conflicts, sharding/`.global()`. |
12
+ | Skill | Use for |
13
+ | -------------------------------- | ---------------------------------------------------------------------------- |
14
+ | `lunora` | Router — start here, then switch to the matching skill below. |
15
+ | `lunora-quickstart` | `lunora init` / adding Lunora to an app + first round-trip. |
16
+ | `lunora-functions` | Core authoring rules — schema, validators, query/mutation/action, `ctx.db`. |
17
+ | `lunora-realtime` | Client reactivity — live hooks, optimistic updates, `@lunora/db`. |
18
+ | `lunora-setup-auth` | Authentication via `lunora registry add auth` (+ providers). |
19
+ | `lunora-setup-mail` | Transactional email via `lunora registry add mail` — `sendEmail` actions. |
20
+ | `lunora-setup-storage` | R2 file storage via `lunora registry add storage` — signed upload/download. |
21
+ | `lunora-setup-scheduler` | Deferred (`ctx.scheduler`) + cron jobs (`lunora registry add crons`). |
22
+ | `lunora-setup-hyperdrive` | Existing Postgres/MySQL from an action — `ctx.sql`, non-reactive. |
23
+ | `lunora-setup-hyperdrive-global` | Postgres/MySQL as a reactive `.global()` backend; D1 → Hyperdrive migration. |
24
+ | `lunora-create-package` | Building a reusable registry item or `@lunora/*` package. |
25
+ | `lunora-migration-helper` | Schema/data migrations, `.global()` DDL flow, the drift gate. |
26
+ | `lunora-deploy` | Deploying to Cloudflare — wrangler bindings, secrets, the gate. |
27
+ | `lunora-performance-audit` | `lunora insights`, scans, indexes, OCC conflicts, sharding/`.global()`. |
26
28
 
27
29
  These are mirrored into `.agents/skills/` and `.claude/skills/` (via symlinks)
28
30
  so agents working inside this repo pick them up directly. The source of truth
29
31
  lives here so the published `@lunora/cli` tarball carries them.
32
+
33
+ **Adding a skill?** Create it here, then mirror it through both hops:
34
+
35
+ ```bash
36
+ ln -s ../../packages/cli/skills/<name> .agents/skills/<name>
37
+ ln -s ../../.agents/skills/<name> .claude/skills/<name>
38
+ ```
39
+
40
+ `scripts/check-skill-mirrors.js` (run on every `pnpm install`) fails if a mirror
41
+ is missing, dangling, or has become a real directory — a copied directory keeps
42
+ resolving while it silently drifts from the source, so it is treated as an
43
+ error rather than a warning.
package/skills/lunora/SKILL.md CHANGED
@@ -14,8 +14,9 @@ Lunora exposes a Convex-style functional API (`defineSchema`, `query`,
14
14
  `mutation`, `action`) on top of Cloudflare Workers and Durable Objects. State
15
15
  lives in a per-app `ShardDO` (SQLite, OCC, hibernated WebSocket subscriptions)
16
16
  by default; `.shardBy(key)` partitions it across many DOs and `.global()`
17
- replicates a table to D1 for low-latency cross-region reads. A Vite plugin
18
- drives codegen and end-to-end type sync.
17
+ replicates a table to D1 — or to Postgres/MySQL over Hyperdrive — for
18
+ low-latency cross-region reads. A Vite plugin drives codegen and end-to-end
19
+ type sync.
19
20
 
20
21
  If a more specific Lunora skill clearly matches the request, use that instead.
21
22
 
@@ -47,12 +48,13 @@ After codegen is green, use the most specific Lunora skill for the task:
47
48
  - Wiring live data into a client (hooks, optimistic updates): `lunora-realtime`
48
49
  - Authentication setup (email/password, OAuth, magic link, OTP):
49
50
  `lunora-setup-auth`
50
- - Wiring a prebuilt capability (mail, file storage, scheduled jobs, rate
51
- limiting, vectors, AI, containers, payments, MCP): install it with
52
- `lunora registry add <item>` (see `lunora registry list`). Capabilities with a
53
- dedicated skill: `lunora-setup-mail` (mail), `lunora-setup-storage` (R2 file
54
- storage), `lunora-setup-scheduler` (deferred `ctx.scheduler` + cron jobs). For
55
- the rest, read the item's README after installing.
51
+ - Transactional email: `lunora-setup-mail`
52
+ - R2 file storage (signed upload/download): `lunora-setup-storage`
53
+ - Deferred work (`ctx.scheduler`) and cron jobs: `lunora-setup-scheduler`
54
+ - Querying an **existing** Postgres/MySQL database from an action (`ctx.sql`,
55
+ non-reactive): `lunora-setup-hyperdrive`
56
+ - Using Postgres/MySQL as a **reactive `.global()` backend**, or migrating a D1
57
+ `.global()` dataset onto it: `lunora-setup-hyperdrive-global`
56
58
  - Building a reusable capability — a registry item or an `@lunora/*` package:
57
59
  `lunora-create-package`
58
60
  - Planning or running a schema/data migration: `lunora-migration-helper`
@@ -64,6 +66,41 @@ After codegen is green, use the most specific Lunora skill for the task:
64
66
  If one of those clearly matches the user's goal, switch to it instead of staying
65
67
  in this skill.
66
68
 
69
+ ## Capabilities Without a Dedicated Skill
70
+
71
+ Most other capabilities install as a **registry item** — `lunora registry add
72
+ <item>` scaffolds the `lunora/` glue, wrangler bindings, and env vars, then
73
+ prints post-install steps. Browse with `lunora registry list`; preview with
74
+ `lunora registry view <item>`. Read the installed item's README, and the
75
+ package's `docs/` for the API.
76
+
77
+ | Goal | Install / package |
78
+ | --------------------------------------------- | ------------------------------------------------------------ |
79
+ | Background jobs on Cloudflare Queues | `registry add queue` → `@lunora/queue` (`ctx.queues`) |
80
+ | Durable multi-step workflows | `registry add workflow` → `@lunora/workflow` (`ctx.runStep`) |
81
+ | Durable AI agents (tool loops, HITL, memory) | `@lunora/agent` (`defineAgent`) |
82
+ | Workers AI / RAG | `registry add ai` → `@lunora/ai` (`ctx.ai`, `defineRag`) |
83
+ | Feature flags (OpenFeature) | `registry add flags` → `@lunora/flags` (`ctx.flags`) |
84
+ | Payments (Stripe / Polar) | `registry add payment` → `@lunora/payment` |
85
+ | Rate limiting | `registry add ratelimit` → `@lunora/ratelimit` |
86
+ | Headless browser (action-only) | `registry add browser` → `@lunora/browser` (`ctx.browser`) |
87
+ | Cloudflare Containers | `@lunora/container` (`defineContainer`, `ctx.containers`) |
88
+ | Presence / who's-here | `registry add presence` |
89
+ | Cloudflare Access (Zero Trust) identity | `registry add cloudflare-access` |
90
+ | Backup / restore | `registry add backup` |
91
+ | Testing (in-memory harness, agent doubles) | `@lunora/testing` (`lunoraTest`) |
92
+ | Deterministic seed data | `@lunora/seed` + `lunora seed` |
93
+ | Local-first replica / offline mirror | `@lunora/replica` |
94
+ | Exposing the deployment to AI agents over MCP | `@lunora/mcp` |
95
+
96
+ Scaffolding inside this repo uses `vis generate lunora-<kind>` — `query`,
97
+ `mutation`, `action`, `http-route`, `table`, `cron`, `container`, `workflow`,
98
+ `queue`, `step`, `agent`, `flags`, `collections`, `package` (`vis generate
99
+ --list` for the full set). Most take a name: **always** pass it as
100
+ `--name=value`, since vis parses a space-separated `--name foo` as `--name=true`
101
+ plus a stray positional. `lunora-flags` and `lunora-collections` are singletons
102
+ and take no name.
103
+
67
104
  ## Core Mental Model
68
105
 
69
106
  - **Functions** live in `lunora/*.ts` and are one of `query` (reactive read),
@@ -75,7 +112,9 @@ in this skill.
75
112
  - **Reads go through indexes.** Prefer `ctx.db.query("t").withIndex(...)` over
76
113
  `.filter(...)`; declare the index with `.index("by_x", ["x"])`.
77
114
  - **Clients** subscribe over WebSocket. `useQuery`/`useMutation` (React, Vue,
78
- Solid, Svelte) re-render the moment a mutation changes the queried rows.
115
+ Solid, Svelte, React Native; signals in Angular) re-render the moment a
116
+ mutation changes the queried rows. Subscriptions run under the socket's
117
+ verified identity, so `rls()` / `ctx.auth` apply to live updates too.
79
118
 
80
119
  ## When Not to Use
81
120
 
package/skills/lunora-functions/SKILL.md CHANGED
@@ -150,9 +150,44 @@ Declare the index and constrain with `.withIndex`.
150
150
 
151
151
  ## Other `ctx` capabilities
152
152
 
153
- `ctx.auth` (the resolved session: `ctx.auth.userId`), `ctx.scheduler`
154
- (`runAfter` / `runAt` for deferred work), `ctx.storage` (R2), `ctx.vectors`
155
- (Vectorize), and — when their packages are wired — `ctx.ai` and `ctx.containers`.
153
+ Always available:
154
+
155
+ - `ctx.auth` — the resolved session (`ctx.auth.userId`).
156
+ - `ctx.scheduler` — `runAfter` / `runAt` for deferred work.
157
+ - `ctx.secrets` — Cloudflare Secrets Store.
158
+ - `ctx.span` / `ctx.trace` — the current span and a scoped tracing helper for
159
+ wide events.
160
+
161
+ Added by their package when wired. **A dependency in `package.json` is not
162
+ enough** — codegen scans the `lunora/` source set and flips a capability on only
163
+ when a file there imports the `@lunora/*` package or reads its `ctx.*` helper.
164
+ So write the call first, then run `lunora codegen` to surface the typed context:
165
+
166
+ | `ctx.*` | Package |
167
+ | ----------------------------------------------------------------------------------------- | ----------------------------- |
168
+ | `ctx.storage` | `@lunora/storage` (R2) |
169
+ | `ctx.ai` | `@lunora/ai` (Workers AI) |
170
+ | `ctx.flags` | `@lunora/flags` (OpenFeature) |
171
+ | `ctx.queues.<name>` | `@lunora/queue` |
172
+ | `ctx.workflows` / `ctx.runStep` | `@lunora/workflow` |
173
+ | `ctx.containers` | `@lunora/container` |
174
+ | `ctx.browser` (action-only) | `@lunora/browser` |
175
+ | `ctx.sql` (action-only) | `@lunora/hyperdrive` |
176
+ | `ctx.kv` / `ctx.images` / `ctx.analytics` / `ctx.pipelines` / `ctx.vectors` / `ctx.r2sql` | `@lunora/bindings` subpaths |
177
+
178
+ Two exceptions to the usage scan, and one extra requirement:
179
+
180
+ - **`ctx.flags` gates on a declaration file**, not on usage — codegen wires it
181
+ only when `lunora/flags.ts` exists (`vis generate lunora-flags` creates it).
182
+ `ctx.notify` / `ctx.push` work the same way via `lunora/notify.ts`.
183
+ - **`ctx.sql` also needs the real resource.** Codegen types the field, but the
184
+ connection needs a `HYPERDRIVE` binding (`wrangler hyperdrive create`) and an
185
+ explicit `createHyperdrive(ctx.env.HYPERDRIVE)` + driver adapter in the
186
+ action — see `lunora-setup-hyperdrive`. Bindings codegen can provision on its
187
+ own (e.g. `BROWSER` for `ctx.browser`) need no manual wrangler step.
188
+
189
+ `ctx.browser` and `ctx.sql` are **action-only** by design — they are
190
+ non-deterministic and would break query reactivity and mutation replay.
156
191
 
157
192
  ## HTTP endpoints
158
193
 
package/skills/lunora-migration-helper/SKILL.md CHANGED
@@ -2,7 +2,8 @@
2
2
  name: lunora-migration-helper
3
3
  description: Plans Lunora schema and data migrations with widen-migrate-narrow. Use for
4
4
  breaking schema changes, backfills, table reshaping, online data migrations
5
- (`defineMigration` + `lunora migrate up`), the `.global()` D1 SQL flow, and the
5
+ (`defineMigration` + `lunora migrate up`), the `.global()` D1 / Hyperdrive
6
+ structural flows, and the
6
7
  pre-deploy schema-drift gate.
7
8
  ---
8
9
 
@@ -15,7 +16,7 @@ Safely change a Lunora schema and migrate data when making breaking changes.
15
16
  - Adding required fields to existing tables.
16
17
  - Changing field types or structure.
17
18
  - Splitting/merging tables, renaming/removing fields.
18
- - Reshaping `.global()` (D1-backed) tables.
19
+ - Reshaping `.global()` tables (D1- or Hyperdrive-backed).
19
20
 
20
21
  ## When Not to Use
21
22
 
@@ -23,21 +24,35 @@ Safely change a Lunora schema and migrate data when making breaking changes.
23
24
  - Adding **optional** fields that need no backfill.
24
25
  - Adding new tables or indexes with no correctness concern.
25
26
 
26
- ## Two Storage Layers — Know Which You Are Migrating
27
+ ## Storage Layers — Know Which You Are Migrating
27
28
 
28
- Lunora tables live in one of two backends, and they migrate differently:
29
+ Lunora tables live in one of three backends, and they migrate differently:
29
30
 
30
31
  - **ShardDO SQLite (default `root`, and `.shardBy(key)` tables).** State lives in
31
32
  the per-app / per-shard Durable Object. Data is reshaped with **online data
32
33
  migrations** — `defineMigration` declarations run by `lunora migrate up`,
33
34
  resumable per shard.
34
- - **`.global()` tables (D1).** Replicated to D1 for cross-region reads. Their
35
- structural DDL gets versioned **SQL migrations** via `lunora migrate generate`,
36
- applied by `@lunora/d1`'s runner at deploy time.
37
-
38
- A breaking change to a `.global()` table needs a generated SQL migration; a data
39
- backfill (either layer) is an online `defineMigration`. Both follow the same
40
- **widen → migrate → narrow** discipline.
35
+ - **`.global()` on D1 (the default global backend).** Replicated to D1 for
36
+ cross-region reads. Structural DDL gets versioned **SQL migrations** via
37
+ `lunora migrate generate`, applied by `@lunora/d1`'s runner at deploy time.
38
+ - **`.global({ backend: "hyperdrive" })` on Postgres/MySQL.** The same reactive
39
+ `.global()` contract served over Cloudflare Hyperdrive. Structural DDL works
40
+ differently here: tables **auto-provision on first use** — the runtime applies
41
+ the DDL through the dialect — so there is no `lunora migrate generate` step
42
+ and no versioned SQL file to commit. See `lunora-setup-hyperdrive-global`.
43
+
44
+ So: a breaking structural change to a **D1-backed** `.global()` table needs a
45
+ generated SQL migration; the Hyperdrive-backed equivalent provisions itself. A
46
+ data backfill (any layer) is always an online `defineMigration`. All three
47
+ follow the same **widen → migrate → narrow** discipline — check the table's
48
+ backend before assuming which structural path applies.
49
+
50
+ > **Moving an existing dataset between global backends.** To move a `.global()`
51
+ > dataset from D1 onto Hyperdrive, use
52
+ > `lunora migrate d1-to-hyperdrive --from-url <d1-worker> --to-url <hd-worker>`
53
+ > (`--tables` scopes it; `--out` keeps the intermediate NDJSON dump). This is a
54
+ > backend move, not a schema change — the widen → migrate → narrow discipline
55
+ > below still governs any reshaping you do on either side of it.
41
56
 
42
57
  ## Key Principle: Widen, Migrate, Narrow
43
58
 
@@ -129,7 +144,10 @@ lunora migrate down backfill-display-name # revert (if `down` defined)
129
144
  Useful flags: `--batch-size <n>`, `--steps <n>` (cap batches this run), and
130
145
  `--prod --url <worker> --yes` to target production (with `LUNORA_ADMIN_TOKEN`).
131
146
 
132
- ## `.global()` (D1) Structural Migration Flow
147
+ ## `.global()` on D1 — Structural Migration Flow
148
+
149
+ This flow is **D1-specific**. Hyperdrive-backed globals auto-provision their DDL
150
+ at runtime and skip it entirely.
133
151
 
134
152
  ```bash
135
153
  # 1. Edit lunora/schema.ts (widen: add the optional new field to the .global() table).
@@ -146,8 +164,8 @@ lunora deploy
146
164
  ```
147
165
 
148
166
  `lunora migrate generate` only considers `.global()` tables (root/sharded tables
149
- are not D1-backed). Run it after each schema edit in the widen and narrow steps;
150
- backfill data with an online migration between them.
167
+ live in ShardDO SQLite, not D1). Run it after each schema edit in the widen and
168
+ narrow steps; backfill data with an online migration between them.
151
169
 
152
170
  ## The Schema-Drift Gate
153
171
 
@@ -176,9 +194,10 @@ add the migration — not to bypass it.
176
194
  transform before it touches real rows.
177
195
  5. **Deleting a field prematurely.** Deprecate with `v.optional` + a comment;
178
196
  delete only once nothing references it.
179
- 6. **Migrating the wrong layer.** A `.global()` structural change needs `lunora
180
- migrate generate` (SQL); a data backfill needs a `defineMigration`. Check the
181
- table's `.global()` / `.shardBy()` modifier first.
197
+ 6. **Migrating the wrong layer.** A D1-backed `.global()` structural change needs
198
+ `lunora migrate generate` (SQL); a Hyperdrive-backed one auto-provisions; a
199
+ data backfill needs a `defineMigration`. Check the table's `.global()` /
200
+ `.shardBy()` modifier — and, for `.global()`, its `backend` — first.
182
201
 
183
202
  ## Checklist
184
203
 
package/skills/lunora-performance-audit/SKILL.md CHANGED
@@ -2,8 +2,8 @@
2
2
  name: lunora-performance-audit
3
3
  description: Diagnoses and fixes Lunora performance problems — full-table scans, missing
4
4
  indexes, OCC write conflicts, oversized subscriptions, and sharding/`.global()`
5
- scaling. Use when queries are slow, mutations conflict, or `@lunora/advisor`
6
- flags a table.
5
+ scaling. Use when queries are slow, mutations conflict, `lunora insights`
6
+ reports a hot-spot, or `@lunora/advisor` flags a table.
7
7
  ---
8
8
 
9
9
  # Lunora Performance Audit
@@ -34,12 +34,35 @@ apply it across sibling functions consistently.
34
34
 
35
35
  ## Signal Gathering
36
36
 
37
- Start with the static advisors — they need no traffic:
37
+ ### Runtime signal: `lunora insights`
38
+
39
+ When the worker is running and has served traffic, start here — it reports the
40
+ measured problem, not a suspected one:
41
+
42
+ ```bash
43
+ lunora insights # against the local dev worker
44
+ lunora insights --shard channel:demo # scope to one shard
45
+ lunora insights --limit 25 --json # machine-readable, more rows
46
+ lunora insights --prod --url https://app.example.com --token $LUNORA_ADMIN_TOKEN
47
+ ```
48
+
49
+ It ranks per-function **write-conflict hot-spots** (OCC contention — the
50
+ sharding signal), **error rates**, and **latency outliers**. A function at the
51
+ top of the write-conflict list is the direct input to the OCC section below; a
52
+ latency outlier usually resolves to the read-amplification section.
53
+
54
+ The Studio **Issues** panel and `lunora logs` cover the error side in more
55
+ detail once `insights` tells you where to look.
56
+
57
+ ### Static signal: the advisors
58
+
59
+ These need no traffic, so they also work on a cold codebase:
38
60
 
39
61
  - **Lunora Studio → Advisors tab** surfaces `@lunora/advisor` findings live in
40
62
  dev.
41
- - `@lunora/advisor` runs static lints over `defineSchema` + discovered query
42
- reads / insert writes. Relevant performance/schema rules:
63
+ - `@lunora/advisor` runs ~90 static lints over `defineSchema` + discovered query
64
+ reads / insert writes (plus a few runtime lints). The performance/schema rules
65
+ most relevant here:
43
66
  - `filter-without-index` — a query filters a table with no covering index.
44
67
  - `unindexed-foreign-key` — a relation/FK column has no index.
45
68
  - `duplicate-index` / `empty-index` — wasted or malformed indexes.
@@ -75,7 +98,8 @@ column. Fix every sibling query on the table the same way.
75
98
 
76
99
  ## Problem Class: Write Conflicts (OCC)
77
100
 
78
- **Symptom:** mutations on hot rows retry or fail under concurrency. ShardDO uses
101
+ **Symptom:** mutations on hot rows retry or fail under concurrency, or the
102
+ function tops the write-conflict section of `lunora insights`. ShardDO uses
79
103
  optimistic concurrency control — concurrent writes to the same DO that touch
80
104
  overlapping state conflict and retry.
81
105
 
@@ -115,6 +139,11 @@ cross-region reads (with read-your-writes via the Sessions API). Reserve it for
115
139
  read-mostly tables — `.global()` adds the D1 migration flow (see the
116
140
  `lunora-migration-helper` skill) and write-path cost.
117
141
 
142
+ If the dataset outgrows D1, `.global({ backend: "hyperdrive" })` serves the same
143
+ reactive `.global()` contract from Postgres/MySQL over Cloudflare Hyperdrive —
144
+ see the `lunora-setup-hyperdrive-global` skill (and `lunora migrate
145
+ d1-to-hyperdrive` to move an existing dataset).
146
+
118
147
  ### `.shardBy(key)` vs `.global()` — choose one per table
119
148
 
120
149
  - `.shardBy(key)`: partitions a table across Durable Objects by key — scales
@@ -135,6 +164,7 @@ read-mostly tables — `.global()` adds the D1 migration flow (see the
135
164
  ## Checklist
136
165
 
137
166
  - [ ] Scoped one concrete flow; traced every `ctx.db` read/write.
167
+ - [ ] Ran `lunora insights` (if the worker has traffic) for the measured signal.
138
168
  - [ ] Checked the Studio Advisors tab / `@lunora/advisor` findings.
139
169
  - [ ] Read amplification: replaced `.filter()` with an indexed `.withIndex()`.
140
170
  - [ ] Write conflicts: narrowed writes and/or partitioned with `.shardBy(key)`.
package/skills/lunora-quickstart/SKILL.md CHANGED
@@ -45,28 +45,65 @@ Set up a working Lunora project as fast as possible.
45
45
  plugin + `lunora/` already wired together).
46
46
 
47
47
  ```bash
48
- lunora init my-app --template vite
48
+ lunora init my-app --vite react
49
49
  cd my-app
50
50
  pnpm install
51
51
  ```
52
52
 
53
- ### Pick a template
53
+ ### Pick a stack: `--vite` (SPA) or `-t` (bespoke template)
54
54
 
55
- | Template | Stack |
56
- | ---------------------- | ---------------------------------------------- |
57
- | `vite` | React + Vite (the simplest full-stack starter) |
58
- | `standalone` | Worker-only Lunora backend, no frontend |
59
- | `astro` | Astro integration |
60
- | `next` | Next.js (App Router, OpenNext on Cloudflare) |
61
- | `nuxt` | Nuxt (Vue) |
62
- | `sveltekit` | SvelteKit |
63
- | `tanstack-start-react` | TanStack Start (React) |
64
- | `tanstack-start-solid` | TanStack Start (Solid) |
55
+ There are **two scaffold paths**, and they take different flags:
65
56
 
66
- If the user has not specified a preference, default to `vite`. Pass `--template`
67
- explicitly to avoid the interactive prompt. Templates are fetched remotely (via
68
- `giget`) from `gh:anolilab/lunora/templates/<type>`; pass `--from <dir>` to use a
69
- local template directory offline.
57
+ **`--vite <framework>` — the create-vite overlay.** Fetches the official
58
+ create-vite base and applies the Lunora layer on top. Use it for a plain SPA:
59
+
60
+ | `--vite` value | Stack |
61
+ | -------------- | ----------------------------------------------- |
62
+ | `react` | React SPA (**the default**) |
63
+ | `vue` | Vue SPA |
64
+ | `solid` | Solid SPA |
65
+ | `svelte` | Svelte SPA |
66
+ | `vanilla` | No framework (overlay-only — not in the picker) |
67
+
68
+ **`-t` / `--template <type>` — a bespoke Lunora template.** Whole-project
69
+ templates fetched remotely (via `giget`) from
70
+ `gh:anolilab/lunora/templates/<type>`:
71
+
72
+ | `-t` value | Stack |
73
+ | ---------------------- | ---------------------------------------------------------- |
74
+ | `next` | Next.js (App Router, OpenNext on Cloudflare) |
75
+ | `tanstack-start-react` | TanStack Start (React) — SSR with live-loader routes |
76
+ | `tanstack-start-solid` | TanStack Start (Solid) |
77
+ | `react-router` | React Router v7 (framework mode), SSR in the Lunora worker |
78
+ | `astro` | Astro + a standalone Lunora worker |
79
+ | `analog` | AnalogJS (Angular) — single worker, Lunora in Nitro |
80
+ | `nuxt` | Nuxt (Vue) — single worker, Lunora in Nitro |
81
+ | `sveltekit` | SvelteKit + a standalone Lunora worker |
82
+ | `expo` | React Native (Expo) — iOS/Android/web + a Lunora worker |
83
+ | `standalone` | Worker-only Lunora backend, no frontend |
84
+
85
+ > There is **no `--template vite`.** SPAs go through `--vite <framework>`; `-t`
86
+ > is only for the bespoke templates above.
87
+
88
+ With neither flag, an interactive run shows the framework picker (defaulting to
89
+ the React overlay) and a **non-interactive run errors out** — so as an agent,
90
+ always pass `--vite` or `-t` explicitly. If the user stated no preference,
91
+ use `--vite react`.
92
+
93
+ ### Useful `init` flags
94
+
95
+ ```bash
96
+ lunora init my-app --vite react --ci github # + a GitHub Actions deploy pipeline (or --ci gitlab)
97
+ lunora init my-app -t next --add auth,email # scaffold capabilities non-interactively
98
+ lunora init my-app --vite react --yes # skip the interactive auth/email offer
99
+ lunora init my-app --vite react --dry-run # walk every step, write nothing
100
+ ```
101
+
102
+ `--add` accepts a comma-separated list of `ai | auth | backup | browser |
103
+ cloudflare-access | crons | email | flags | hyperdrive | payment | presence |
104
+ queue | storage | workflow`. `--ref <branch|tag|commit>` pins the template
105
+ source (e.g. `--ref alpha`); `--from <dir>` copies from a local templates root
106
+ offline (expects `<type>/` subdirs).
70
107
 
71
108
  ### Generate types and push the first run
72
109
 
@@ -152,9 +189,12 @@ createRoot(document.querySelector("#root")!).render(
152
189
  );
153
190
  ```
154
191
 
155
- Vue, Solid, and Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
156
- and `@lunora/svelte`. `VITE_LUNORA_URL` is optional — it defaults to
157
- `location.origin`, which is correct for the single-origin dev setup.
192
+ Every client adapter has a matching provider: `@lunora/vue`, `@lunora/solid`,
193
+ `@lunora/svelte`, `@lunora/angular` (`provideLunora` / `injectLunoraClient`),
194
+ and `@lunora/react-native` (`createLunoraClient`, re-exporting `@lunora/react`).
195
+ For meta-frameworks, `@lunora/astro` and `@lunora/nuxt` mount Lunora on the
196
+ server side. `VITE_LUNORA_URL` is optional — it defaults to `location.origin`,
197
+ which is correct for the single-origin dev setup.
158
198
 
159
199
  ## Writing Your First Function
160
200
 
@@ -253,7 +293,8 @@ ids, `.dev.vars` secrets, and container exports.
253
293
  ## Checklist
254
294
 
255
295
  - [ ] Determined starting point: new project or existing app.
256
- - [ ] New project: scaffolded with `lunora init --template <t>`.
296
+ - [ ] New project: scaffolded with `lunora init --vite <framework>` (SPA) or
297
+ `lunora init -t <template>` (bespoke) — never `--template vite`.
257
298
  - [ ] Existing app: ran `lunora init --here` and wired `LunoraProvider`.
258
299
  - [ ] Ran `lunora codegen`: `lunora/_generated/` exists and typecheck is clean.
259
300
  - [ ] Dev server is running — user terminal, or `lunora dev --background`
package/skills/lunora-realtime/SKILL.md CHANGED
@@ -2,8 +2,8 @@
2
2
  name: lunora-realtime
3
3
  description: Wires Lunora's live data into a client. Use for `LunoraClient`/`LunoraProvider`,
4
4
  reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates,
5
- pagination, connection status, the React/Vue/Solid/Svelte adapters, and the
6
- `@lunora/db` TanStack binding.
5
+ pagination, connection status, the React/Vue/Solid/Svelte/Angular/React Native
6
+ adapters, and the `@lunora/db` TanStack binding.
7
7
  ---
8
8
 
9
9
  # Lunora Realtime
@@ -15,7 +15,8 @@ automatic rollback.
15
15
 
16
16
  ## When to Use
17
17
 
18
- - Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
18
+ - Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte, Angular,
19
+ React Native/Expo, or an Astro/Nuxt meta-framework).
19
20
  - Adding optimistic updates, pagination, or presence to the UI.
20
21
  - Choosing between live hooks and the `@lunora/db` collection layer.
21
22
 
@@ -42,6 +43,19 @@ const client = new LunoraClient({ url });
42
43
  Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
43
44
  `@lunora/svelte`; the hook names and semantics below mirror across them.
44
45
 
46
+ Two adapters differ in shape:
47
+
48
+ - **`@lunora/angular`** is signal-based rather than hook-based: register with
49
+ `provideLunora(...)`, read the client via `injectLunoraClient()`, and use
50
+ `liveQuery(...)` / `mutate(...)` / `connectionStatus(...)` in place of the
51
+ hooks below.
52
+ - **`@lunora/react-native`** re-exports all of `@lunora/react` and adds
53
+ `createLunoraClient` (plus `@lunora/react-native/auth` for the better-auth
54
+ Expo bridge) — build the client with that instead of `new LunoraClient`.
55
+
56
+ For SSR meta-frameworks, `@lunora/astro` and `@lunora/nuxt` compose Lunora into
57
+ the server (Nitro for Nuxt) and ship reactive-loader server helpers.
58
+
45
59
  ## Live Queries
46
60
 
47
61
  `useQuery(reference, args)` opens a subscription and returns the value, or
@@ -67,33 +81,32 @@ const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
67
81
 
68
82
  ## Authorization & Live Queries
69
83
 
70
- Subscriptions re-run the query handler **server-side under anonymous
71
- identity**. The one-shot `fetch` RPC behind the initial load carries the
72
- caller's identity, but the live WebSocket channel (the subscription seed and
73
- every write-driven refresh) does not — it evaluates as anonymous.
74
-
75
- This matters for any query that authorizes or filters on the authenticated
76
- user:
77
-
78
- - A query guarded by `.use(rls(...))` or one that reads `ctx.auth.userId`
79
- directly returns the user's rows on the **initial** HTTP fetch, but its
80
- **live** updates evaluate anonymously and may resolve to an empty/denied
81
- set.
82
- - This **fails closed** — the live channel shows _less_ data, never another
83
- user's data, so there is no leak. But it is a correctness caveat: the
84
- initial render and the live updates can disagree.
85
-
86
- The supported pattern today is to scope per-user data **outside** of
87
- `ctx.auth` inside a subscribed query:
88
-
89
- - Partition the data by shard with `.shardBy(userId)` (or tenant/room), so the
90
- subscription is already scoped to the right state, or
91
- - Pass the identifier as an **explicit query arg**
92
- (`useQuery(api.todos.list, { userId })`) and filter on the arg rather than on
93
- `ctx.auth`.
94
-
95
- Reserve `rls()` / `ctx.auth`-based filtering for non-subscribed reads (one-shot
96
- actions/queries) where identity is always present.
84
+ **Live queries are identity-aware.** At the WebSocket upgrade the runtime
85
+ stamps the caller's verified identity onto the socket (from the server-minted
86
+ `x-lunora-userid` / `x-lunora-identity` headers, which a client cannot forge).
87
+ Every subscription re-run, shape resolution, and poke-driven refresh executes
88
+ under that socket's own identity, passed by value so a concurrent RPC can't
89
+ clobber it.
90
+
91
+ Practically, this means:
92
+
93
+ - `.use(rls(...))` and `ctx.auth.userId` work the same in a subscribed query as
94
+ in a one-shot read. Shape subscriptions AND-merge the shape predicate with
95
+ the table's RLS read base-where, so the membership query the poke protocol
96
+ runs is RLS-correct by construction — never the client's word for it.
97
+ - An **anonymous** socket carries no identity, so an RLS/`ctx.auth` query fails
98
+ closed (empty/denied) rather than leaking another user's rows.
99
+ - **Token expiry is enforced on the socket.** When the resolved credential
100
+ carries an expiry, the DO sends a `TOKEN_EXPIRED` error frame and closes with
101
+ code `4001` at the next send at or after that instant. `LunoraClient`
102
+ reconnects automatically and re-resolves a fresh identity — but surface it in
103
+ the UI if a re-login is required.
104
+
105
+ You can still scope data structurally when it fits the domain — `.shardBy(userId)`
106
+ (or tenant/room) partitions state so a subscription is narrow by construction,
107
+ and explicit query args keep subscriptions cheap (see the args-scoping note
108
+ above). Prefer those for _performance_; use `rls()` / `ctx.auth` for
109
+ _authorization_. They compose.
97
110
 
98
111
  ## Mutations + Optimistic Updates
99
112