@spooky-sync/cli 0.0.1-canary.63 → 0.0.1-canary.65

package/AGENTS.md

@@ -0,0 +1,76 @@
+# `@spooky-sync/cli` (`spky`) — agent guide
+
+## What this package is
+
+The sp00ky toolchain. A Rust binary (`spky`) plus a thin npm wrapper. It parses `.surql` schemas, emits typed `schema.gen.ts` (and `.dart`), runs migrations, manages buckets and API backends, drives the local dev environment, and orchestrates Sp00ky Cloud deployments.
+
+## Binary
+
+```
+spky <subcommand> [flags]
+```
+
+Installed via `npx @spooky-sync/cli` or globally as `spky`. The `bin` field in `package.json` is `spky` — *not* `sp00ky`.
+
+## Project layout it expects
+
+```
+your-app/
+├── sp00ky.yml              # config: schema path, generated outputs, backends, buckets
+├── schema/
+│   └── schema.surql        # source of truth — your domain model
+├── src/
+│   └── schema.gen.ts       # GENERATED — never hand-edit
+└── migrations/             # GENERATED migrations; modified files are tracked by checksum
+```
+
+`spky` finds `sp00ky.yml` in the current directory by default; pass `--config <path>` to override.
+
+## Subcommands an app developer/agent uses most
+
+- **`spky generate` / `spky gen`** — read `sp00ky.yml`, parse all `.surql`, emit `schema.gen.ts` (and Dart equivalents per config). **Run this after every schema edit.**
+- **`spky migrate create <name>`** — diff current schema against the last applied migration and emit a new `.surql` migration file.
+- **`spky migrate apply`** — apply pending migrations against the configured database. `--fix-checksums` updates stored checksums for legitimately-modified migration files.
+- **`spky migrate status`** — show pending vs applied vs modified-but-applied migrations.
+- **`spky migrate fix [--fix-checksums]`** — repair schema drift / checksum mismatches.
+- **`spky verify [--fix]`** — confirm SSP/scheduler snapshot matches upstream SurrealDB. `--fix` triggers a resync.
+- **`spky lint`** — validate `sp00ky.yml` and referenced files exist.
+- **`spky dev [--apply-migrations] [--clean]`** — boots a local SurrealDB + SSP + scheduler stack via Docker. `--clean` wipes SSP/scheduler state but preserves user data in SurrealDB.
+- **`spky create`** — scaffold a new sp00ky project.
+- **`spky bucket add`** / **`spky api add`** — append a bucket or backend definition to `sp00ky.yml`.
+- **`spky mcp`** — start the bundled `@spooky-sync/devtools-mcp` server (so AI assistants can introspect the running app).
+
+## Cloud subcommands (deployment)
+
+`spky cloud login | create | deploy | status | logs | scale | restart | destroy | backup | env | keys | link | team | vault | credentials`. See `spky cloud --help`. Most app code agents touch never need these.
+
+## Schema annotations the parser recognizes
+
+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.
+- `-- @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.
+
+Example:
+```sql
+DEFINE TABLE thread SCHEMAFULL ...;
+
+-- @crdt text
+DEFINE FIELD content ON TABLE thread TYPE string ASSERT $value != NONE;
+
+DEFINE FIELD author ON TABLE thread TYPE record<user>; -- @parent
+```
+
+## Common gotchas
+
+- **`schema.gen.ts` must be regenerated after every `.surql` change.** `spky generate`. CI typically asserts no drift.
+- **Migrations are checksum-tracked.** Editing a previously-applied migration file won't silently re-run; `spky migrate status` flags it. Use `--fix-checksums` only when you're sure the change is semantically a no-op.
+- **`sp00ky.yml` is the entry point.** The CLI never crawls for `.surql`; everything is wired explicitly through the config.
+- **Generation modes matter.** The `--mode` flag (`singlenode`, `cluster`, `surrealism`) changes what the generated client connects to. Default is `singlenode` (HTTP to a single SSP). `surrealism` embeds the WASM stream processor in-browser.
+- **Don't commit the bin output.** The Rust binary is built per-platform and shipped via the npm tarball under `dist/`.
+
+## Pointers
+
+- Sync engine the generated client targets: `node_modules/@spooky-sync/core/AGENTS.md`
+- Reactive UI bindings: `node_modules/@spooky-sync/client-solid/AGENTS.md`
+- Live MCP introspection during dev: `node_modules/@spooky-sync/devtools-mcp/AGENTS.md`

package/devtools-mcp/server.js

@@ -142,6 +142,92 @@ export function createServer(bridge, surreal) {
         await bridge.request(BRIDGE_METHODS.CLEAR_HISTORY, {}, tabId);
         return { content: [{ type: 'text', text: 'History cleared.' }] };
     });
+    server.tool('describe_schema', 'Describe all tables with columns, types, and sp00ky annotations (@crdt, @parent). Stitches INFO FOR DB with parsed schema metadata. With the browser extension this returns @crdt/@parent semantics; direct-DB mode returns raw column info only.', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            const dbState = state?.database ?? {};
+            return json({
+                source: 'extension',
+                tables: dbState.tables ?? [],
+                relationships: dbState.relationships ?? [],
+            });
+        }
+        if (surreal) {
+            const dbInfo = (await surreal.query('INFO FOR DB;'));
+            const tablesObj = dbInfo?.[0]?.result?.tables ?? dbInfo?.[0]?.tables ?? {};
+            const tableNames = Object.keys(tablesObj);
+            const tables = await Promise.all(tableNames.map(async (name) => {
+                try {
+                    const info = (await surreal.query(`INFO FOR TABLE \`${name}\`;`));
+                    const fieldsObj = info?.[0]?.result?.fields ?? info?.[0]?.fields ?? {};
+                    const columns = Object.entries(fieldsObj).map(([fname, def]) => ({
+                        name: fname,
+                        definition: typeof def === 'string' ? def : JSON.stringify(def),
+                    }));
+                    return { name, columns };
+                }
+                catch (e) {
+                    return { name, columns: [], error: e instanceof Error ? e.message : String(e) };
+                }
+            }));
+            return json({
+                source: 'direct-db',
+                note: '@crdt / @parent annotations are not visible in direct-DB mode; connect the browser extension to see them.',
+                tables,
+            });
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('lint_query', 'Validate a SurrealQL query without running it. Sends EXPLAIN <query> through the connected channel; returns parse / plan errors with location when SurrealDB provides them.', {
+        query: z.string().describe('SurrealQL query to validate'),
+        target: z
+            .enum(['local', 'remote'])
+            .optional()
+            .default('remote')
+            .describe('When using the extension: lint against local (cache) or remote DB'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ query, target, tabId }) => {
+        const trimmed = query.trim().replace(/;\s*$/, '');
+        const explainQuery = /^\s*EXPLAIN\b/i.test(trimmed) ? trimmed : `EXPLAIN ${trimmed};`;
+        const parseError = (msg) => {
+            const m = msg.match(/line\s+(\d+)(?:[,\s]+col(?:umn)?\s+(\d+))?/i);
+            return {
+                ok: false,
+                errors: [
+                    {
+                        message: msg,
+                        line: m ? Number(m[1]) : undefined,
+                        column: m && m[2] ? Number(m[2]) : undefined,
+                    },
+                ],
+            };
+        };
+        const inspectResult = (raw) => {
+            const arr = Array.isArray(raw) ? raw : [raw];
+            const errors = arr
+                .map((r) => (r && r.status === 'ERR' ? r.result ?? r.message : null))
+                .filter(Boolean);
+            if (errors.length > 0) {
+                return { ok: false, errors: errors.map((m) => parseError(m).errors[0]) };
+            }
+            return { ok: true, plan: arr };
+        };
+        try {
+            if (bridge.isConnected) {
+                const result = await bridge.request(BRIDGE_METHODS.RUN_QUERY, { query: explainQuery, target }, tabId);
+                return json(inspectResult(result));
+            }
+            if (surreal) {
+                const result = await surreal.query(explainQuery);
+                return json(inspectResult(result));
+            }
+            throw new Error('No extension connected and no direct database configured.');
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return json(parseError(msg));
+        }
+    });
     // --- Resources ---
     server.resource('state', 'sp00ky://state', { description: 'Full Sp00ky DevTools state' }, async (uri) => {
         if (!bridge.isConnected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/cli",
-  "version": "0.0.1-canary.63",
+  "version": "0.0.1-canary.65",
   "description": "Generate TypeScript/Dart types from SurrealDB schema files",
   "type": "module",
   "main": "./dist/syncgen.cjs",
@@ -18,7 +18,9 @@
   },
   "files": [
     "dist",
-    "devtools-mcp"
+    "devtools-mcp",
+    "templates/cookbook",
+    "AGENTS.md"
   ],
   "scripts": {
     "dev": "vite",
@@ -58,10 +60,10 @@
     "vitest": "^1.0.0"
   },
   "optionalDependencies": {
-    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.63",
-    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.63",
-    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.63",
-    "@spooky-sync/cli-linux-x64": "0.0.1-canary.63",
-    "@spooky-sync/cli-win32-x64": "0.0.1-canary.63"
+    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.65",
+    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.65",
+    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.65",
+    "@spooky-sync/cli-linux-x64": "0.0.1-canary.65",
+    "@spooky-sync/cli-win32-x64": "0.0.1-canary.65"
   }
 }

package/templates/cookbook/INDEX.md

@@ -0,0 +1,31 @@
+# sp00ky cookbook
+
+A short, scannable list of patterns an AI agent (or human) reaches for when writing code against a sp00ky-backed app. Each entry has a one-sentence "when to use," the canonical snippet, and one gotcha.
+
+Render any recipe with:
+```
+spky scaffold <recipe> --table <your-table>
+```
+or pass `--out path/to/file.tsx` to write the snippet directly.
+
+## Recipes
+
+### `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`
+**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`
+**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.
+
+## Related
+
+- See `AGENTS.md` (in your project root or `node_modules/@spooky-sync/*/AGENTS.md`) for the broader mental model and gotchas.
+- After editing the schema: `spky generate` then `spky doctor` to confirm everything is in sync.

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

@@ -0,0 +1,36 @@
+// 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.
+
+import { useDb, useQuery, useCrdtField } from '@spooky-sync/client-solid';
+import { schema } from '../schema.gen';
+
+export function {{TablePascal}}{{FieldPascal}}Editor(props: { id: string }) {
+  const db = useDb<typeof schema>();
+
+  // 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}}
+  );
+
+  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 });
+  };
+
+  return (
+    <textarea value={field.value() ?? ''} onInput={handleInput} />
+  );
+}

package/templates/cookbook/live-list.tsx

@@ -0,0 +1,22 @@
+// Recipe: live-list
+// Reactive, sorted list of `{{table}}` rows. Re-runs automatically as records change.
+
+import { For } from 'solid-js';
+import { useQuery, useDb } from '@spooky-sync/client-solid';
+import { schema } from '../schema.gen';
+
+export function {{TablePascal}}List() {
+  const db = useDb<typeof schema>();
+
+  const result = useQuery(() =>
+    db.query('{{table}}').orderBy('id', 'asc').limit(50).build()
+  );
+
+  return (
+    <ul>
+      <For each={result.data() ?? []}>
+        {(row) => <li>{row.id}</li>}
+      </For>
+    </ul>
+  );
+}

package/templates/cookbook/optimistic-mutation.tsx

@@ -0,0 +1,33 @@
+// Recipe: optimistic-mutation
+// Insert a new `{{table}}` row from a UI action. Local cache updates immediately;
+// the mutation drains to the remote in the background.
+
+import { createSignal } from 'solid-js';
+import { Uuid, useDb } from '@spooky-sync/client-solid';
+import { schema } from '../schema.gen';
+
+export function Create{{TablePascal}}Form() {
+  const db = useDb<typeof schema>();
+  const [submitting, setSubmitting] = createSignal(false);
+
+  const handleSubmit = async (e: SubmitEvent) => {
+    e.preventDefault();
+    setSubmitting(true);
+    try {
+      const id = new Uuid().toString();
+      await db.create(`{{table}}:${id}`, {
+        // TODO: fill in the fields your `{{table}}` schema requires.
+      });
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <button type="submit" disabled={submitting()}>
+        {submitting() ? 'Creating…' : 'Create {{table}}'}
+      </button>
+    </form>
+  );
+}