@spooky-sync/cli 0.0.1-canary.323 → 0.0.1-canary.325

package/AGENTS.md

@@ -87,20 +87,21 @@ Two that come up when a deployment misbehaves:
 
 In your `.surql` source, comment annotations attached to `DEFINE FIELD` / `DEFINE TABLE` change codegen output:
 
-- `-- @crdt text` (above a `DEFINE FIELD`) — marks a field as a Loro CRDT text field. Consumers must use `useCrdtField` to read/write it; plain `useQuery` will see stale or unmerged content.
+- `-- @crdt text` / `-- @crdt prosemirror` (above a `DEFINE FIELD ... TYPE string`), optionally with `-- @cursor`: a collaborative Loro field. `crdt_schema::expand` (run by every schema pipeline: server schema, events, internal schema, client schema) rewrites the field into a server-written plain-text mirror (`DEFAULT ''` plus a VALUE guard that keeps `$before` for any record-user write) and generates, per parent `P`: `P__crdt_log` (append-only edit log; create follows P's update rule and select P's select rule, both rebased through the `doc` link on the AST by `rebase_permission`; update/delete NONE; impersonation sessions may not create), `P__crdt_presence` (`@cursor` only), the `<field>__crdt` fold stamp on `P`, a cleanup event, and the shared `_00_crdt_doc` (canonical snapshots, SSP-only) and `_00_crdt_peer` (peer id ownership). It refuses a non-string type, a VALUE/ASSERT on the field, nested fields, relation tables, reserved names (`*__crdt_log`, `*__crdt_presence`, `_00_crdt_doc`, `*__crdt` fields) and the `surrealism` deploy mode. Clients edit through `useCrdtField`; the column itself is readable and filterable like any string. Design: `docs/crdt-v2.md`.
 - `-- @parent` (suffix on `DEFINE FIELD ... TYPE record<...>`) — marks the column as the parent side of a relationship; written automatically from the auth context, never by client code.
 - `-- @nosync` (above a `DEFINE TABLE`) — marks a table as server-only: it is omitted from generated types and relations (and any `record<...>` link pointing at it is dropped), no sync events are emitted for it, and the scheduler/SSP exclude it from snapshots and bootstrap. The table still lives in the main DB and is still backed up. The CLI bakes a `COMMENT 'sp00ky:nosync'` marker onto the server-side `DEFINE TABLE` so the runtime services detect it via `INFO FOR DB`. Distinct from `PERMISSIONS FOR select WHERE false`, which only locks reads — a permission-locked table is still synced.
 - `-- @nosync` (above a `DEFINE FIELD`) — marks a single field server-only: omitted from generated types and from the client's local cache schema, omitted from sync event payloads, and omitted from the scheduler replica and SSP bootstrap row scans. **Not a read barrier**: a client's down-sync `SELECT` still returns the column over the wire, and it is only discarded on arrival (`cleanRecord`). For real secrecy use `PERMISSIONS FOR select WHERE false` on the field, or move it to a `@nosync` table.
 - `-- @opaque` (above a `DEFINE FIELD`) — the field IS synced to the client (it stays in generated types and the local cache, flagged `opaque: true` on the column) but no server-side component stores the value. Intended for large blobs you render but never query on. Because nothing holds the value it cannot be evaluated: using it in `where`/`orderBy`/a join throws in the query builder and is rejected with a 400 at SSP registration, and a schema whose `PERMISSIONS` or `DEFINE INDEX` references one fails to build. Delivery works because sync payloads carry ids + versions, not field values — the client reads the row body straight from SurrealDB.
 
-All three field-level exclusions (`@nosync`, `@crdt`, `@opaque`) get `COMMENT 'sp00ky:opaque'` baked onto the server `DEFINE FIELD` (`schema_builder::add_opaque_field_markers`). The scheduler replica and the SSP bootstrap read that marker from `INFO FOR TABLE` and turn it into a `SELECT * OMIT ...` projection. Both halves are required: skipping a field from the ingest payload while the bootstrap still loads it makes the SSP circuit and the scheduler replica disagree about the row's key set permanently (the replica applies updates with `MERGE`, the circuit replaces the whole row), which shows up as an unfixable `spky verify` mismatch.
+Both field-level exclusions (`@nosync`, `@opaque`) get `COMMENT 'sp00ky:opaque'` baked onto the server `DEFINE FIELD` (`schema_builder::add_opaque_field_markers`). The scheduler replica and the SSP bootstrap read that marker from `INFO FOR TABLE` and turn it into a `SELECT * OMIT ...` projection. Both halves are required: skipping a field from the ingest payload while the bootstrap still loads it makes the SSP circuit and the scheduler replica disagree about the row's key set permanently (the replica applies updates with `MERGE`, the circuit replaces the whole row), which shows up as an unfixable `spky verify` mismatch. A `@crdt` field is not excluded (its mirror is an ordinary synced column) unless it also carries `@opaque`; the generated log's `data` and presence `state` columns are `@opaque` with the marker baked in, because the internal-schema step re-applies those definitions without the marker pass.
 
 Example:
 ```sql
 DEFINE TABLE thread SCHEMAFULL ...;
 
--- @crdt text
-DEFINE FIELD content ON TABLE thread TYPE string ASSERT $value != NONE;
+-- @crdt prosemirror
+-- @cursor
+DEFINE FIELD content ON TABLE thread TYPE string;
 
 DEFINE FIELD author ON TABLE thread TYPE record<user>; -- @parent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/cli",
-  "version": "0.0.1-canary.323",
+  "version": "0.0.1-canary.325",
   "description": "Generate TypeScript/Dart types from SurrealDB schema files",
   "type": "module",
   "main": "./dist/syncgen.cjs",
@@ -62,10 +62,10 @@
     "vitest": "^1.0.0"
   },
   "optionalDependencies": {
-    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.323",
-    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.323",
-    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.323",
-    "@spooky-sync/cli-linux-x64": "0.0.1-canary.323",
-    "@spooky-sync/cli-win32-x64": "0.0.1-canary.323"
+    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.325",
+    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.325",
+    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.325",
+    "@spooky-sync/cli-linux-x64": "0.0.1-canary.325",
+    "@spooky-sync/cli-win32-x64": "0.0.1-canary.325"
   }
 }

package/templates/cookbook/INDEX.md

@@ -4,7 +4,7 @@ A short, scannable list of patterns an AI agent (or human) reaches for when writ
 
 Render any recipe with:
 ```
-spky scaffold <recipe> --table <your-table>
+spky recipe <recipe> --table <your-table>
 ```
 or pass `--out path/to/file.tsx` to write the snippet directly.
 
@@ -12,18 +12,18 @@ or pass `--out path/to/file.tsx` to write the snippet directly.
 
 ### `live-list`
 **When to use:** you want a reactive, sorted list of rows from a table that updates as records change.
-**Render:** `spky scaffold live-list --table thread`
+**Render:** `spky recipe live-list --table thread`
 **Gotcha:** end the query with `.build()` — `useQuery` will hang on a bare builder.
 
 ### `optimistic-mutation`
 **When to use:** you're inserting a new record from a UI action (form submit, button click) and want the local cache to update immediately while the mutation drains to the remote.
-**Render:** `spky scaffold optimistic-mutation --table thread`
+**Render:** `spky recipe optimistic-mutation --table thread`
 **Gotcha:** `db.create` takes a *full* record-ID string (`'thread:abc'`), not `(table, payload)`. Use `Uuid` to mint IDs.
 
 ### `crdt-text-field`
-**When to use:** a text column is annotated `-- @crdt text` in your schema and you need a collaborative editor wired to it.
-**Render:** `spky scaffold crdt-text-field --table thread --field content`
-**Gotcha:** never read the field via `useQuery`; always `useCrdtField`. Writes must pass `{ debounced: true }` to `db.update` so rapid keystrokes coalesce.
+**When to use:** a `TYPE string` field is annotated `-- @crdt text` in your schema and several people should edit it at once.
+**Render:** `spky recipe crdt-text-field --table note --field body`
+**Gotcha:** edit through `useCrdtField(table, () => id, field)` and its `getDoc()`; never put the field in a `db.create` / `db.update` payload (the server owns it). The column itself is the server-written plain text, fine to read with `useQuery` for previews, but it trails live edits until the server folds the edit log. For `@crdt prosemirror` fields bind a ProseMirror editor with `loro-prosemirror` instead of a textarea.
 
 ## Related
 

package/templates/cookbook/crdt-text-field.tsx

@@ -1,36 +1,54 @@
 // Recipe: crdt-text-field
-// Wire a CRDT text column (`{{table}}.{{field}}` annotated `-- @crdt text` in the schema)
-// to a textarea. Concurrent edits from multiple clients merge via Loro.
+// A collaborative textarea for `{{table}}.{{field}}`, declared in the schema as
+//
+//   -- @crdt text
+//   DEFINE FIELD {{field}} ON TABLE {{table}} TYPE string;
+//
+// The editor binds to the field's Loro document. Each client sends only its own
+// edits (rows of the generated `{{table}}__crdt_log` table, through the outbox)
+// and merges everyone else's as they sync; the server folds them into the
+// canonical document. The `{{field}}` column itself is the server-written plain
+// text: render it for previews, never write it with `db.create` / `db.update`.
 
-import { useDb, useQuery, useCrdtField } from '@spooky-sync/client-solid';
+import { createEffect, createSignal, onCleanup, Show } from 'solid-js';
+import { useCrdtField, useDb, useQuery } from '@spooky-sync/client-solid';
 import { schema } from '../schema.gen';
 
 export function {{TablePascal}}{{FieldPascal}}Editor(props: { id: string }) {
-  const db = useDb<typeof schema>();
+  // 3 arguments: table, a reactive record id, field. Reopens when the id changes.
+  const field = useCrdtField('{{table}}', () => props.id, '{{field}}');
+  const [text, setText] = createSignal('');
 
-  // Pull the surrounding row so we know the field is loaded.
-  const rowResult = useQuery(() =>
-    db.query('{{table}}').where({ id: props.id } as any).build()
-  );
-  const row = () => rowResult.data()?.[0];
-
-  // Bind the CRDT field. All four args take accessor functions for SolidJS tracking.
-  const field = useCrdtField(
-    '{{table}}',
-    () => row()?.id,
-    '{{field}}',
-    () => row()?.{{field}}
-  );
+  // Follow the document: local and remote edits alike re-render the textarea.
+  createEffect(() => {
+    const doc = field()?.getDoc();
+    if (!doc) return;
+    const loroText = doc.getText('{{field}}');
+    setText(loroText.toString());
+    onCleanup(doc.subscribe(() => setText(loroText.toString())));
+  });
 
-  const handleInput = async (e: InputEvent) => {
-    const next = (e.currentTarget as HTMLTextAreaElement).value;
-    const r = row();
-    if (!r?.id) return;
-    // `debounced` coalesces rapid keystrokes into a single mutation.
-    await db.update('{{table}}', r.id, { {{field}}: next }, { debounced: true });
+  const handleInput = (e: InputEvent & { currentTarget: HTMLTextAreaElement }) => {
+    const doc = field()?.getDoc();
+    if (!doc) return;
+    // Diff into the document rather than replacing it, so concurrent edits merge.
+    doc.getText('{{field}}').update(e.currentTarget.value);
+    doc.commit();
   };
 
   return (
-    <textarea value={field.value() ?? ''} onInput={handleInput} />
+    <Show when={field()} fallback={<p>Loading...</p>}>
+      <textarea value={text()} onInput={handleInput} />
+    </Show>
+  );
+}
+
+// Previews read the column like any other. It is the document's text as of the
+// server's last fold, so it trails live edits (about a minute by default).
+export function {{TablePascal}}{{FieldPascal}}Preview(props: { id: string }) {
+  const db = useDb<typeof schema>();
+  const result = useQuery(() =>
+    db.query('{{table}}').where({ id: props.id } as any).build()
   );
+  return <p>{result.data()?.[0]?.{{field}}}</p>;
 }