@spooky-sync/cli 0.0.1-canary.21 → 0.0.1-canary.211

package/devtools-mcp/server.js

@@ -0,0 +1,290 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { BRIDGE_METHODS } from './protocol.js';
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+export function createServer(bridge, surreal) {
+    const server = new McpServer({
+        name: 'sp00ky-devtools',
+        version: '0.0.1',
+    });
+    // --- Tools ---
+    server.tool('list_connections', 'List browser tabs connected to Sp00ky DevTools', {}, async () => {
+        return json({ connected: bridge.isConnected, tabs: bridge.getConnectedTabs() });
+    });
+    server.tool('get_state', 'Get the full Sp00ky DevTools state (events, queries, auth, database)', { tabId: z.number().optional().describe('Browser tab ID (uses first connected tab if omitted)') }, async ({ tabId }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. get_state requires the Sp00ky DevTools browser extension.');
+        }
+        const result = await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId);
+        return json(result);
+    });
+    server.tool('run_query', 'Execute a SurrealQL query against the database', {
+        query: z.string().describe('SurrealQL query to execute'),
+        target: z.enum(['local', 'remote']).optional().default('remote').describe('Query target: local or remote database'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ query, target, tabId }) => {
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.RUN_QUERY, { query, target }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(query);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured. Set SURREAL_URL or connect the browser extension.');
+    });
+    server.tool('list_tables', 'List all database tables', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            const tables = state?.database?.tables ?? [];
+            return json(tables);
+        }
+        if (surreal) {
+            const result = await surreal.query('INFO FOR DB;');
+            const info = result;
+            const tables = info?.[0]?.result?.tables ?? info?.[0]?.tables ?? {};
+            return json(Object.keys(tables));
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('get_table_data', 'Fetch records from a database table', {
+        tableName: z.string().describe('Name of the table'),
+        limit: z.number().optional().default(100).describe('Max number of records to return'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ tableName, limit, tabId }) => {
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.GET_TABLE_DATA, { tableName }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(`SELECT * FROM \`${tableName}\` LIMIT ${limit};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('update_table_row', 'Update a record in a database table', {
+        tableName: z.string().optional().describe('Name of the table (used when browser extension is connected)'),
+        recordId: z.string().describe('Record ID to update (e.g. "users:abc123")'),
+        updates: z.record(z.unknown()).describe('Fields to update'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ tableName, recordId, updates, tabId }) => {
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.UPDATE_TABLE_ROW, { tableName, recordId, updates }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(`UPDATE ${recordId} MERGE ${JSON.stringify(updates)};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('delete_table_row', 'Delete a record from a database table', {
+        tableName: z.string().optional().describe('Name of the table (used when browser extension is connected)'),
+        recordId: z.string().describe('Record ID to delete (e.g. "users:abc123")'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ tableName, recordId, tabId }) => {
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.DELETE_TABLE_ROW, { tableName, recordId }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(`DELETE ${recordId};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('get_active_queries', 'Get all active live queries and their data', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            return json(state?.activeQueries ?? []);
+        }
+        if (surreal) {
+            const result = await surreal.query('SELECT * FROM _00_query;');
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('get_events', 'Get event history, optionally filtered by type', {
+        eventType: z.string().optional().describe('Filter by event type'),
+        limit: z.number().optional().default(50).describe('Max number of events to return'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ eventType, limit, tabId }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            let events = state?.eventsHistory ?? [];
+            if (eventType) {
+                events = events.filter((e) => e.eventType === eventType);
+            }
+            if (limit) {
+                events = events.slice(-limit);
+            }
+            return json(events);
+        }
+        if (surreal) {
+            const result = await surreal.query(`SELECT * FROM _00_events ORDER BY timestamp DESC LIMIT ${limit};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('get_auth_state', 'Get the current authentication state', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. get_auth_state requires the Sp00ky DevTools browser extension.');
+        }
+        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+        return json(state?.auth ?? null);
+    });
+    server.tool('clear_history', 'Clear the event history', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. clear_history requires the Sp00ky DevTools browser extension.');
+        }
+        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) {
+            throw new Error('No extension connected. State resource requires the browser extension.');
+        }
+        const state = await bridge.request(BRIDGE_METHODS.GET_STATE);
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(state, null, 2) }] };
+    });
+    server.resource('tables', 'sp00ky://tables', { description: 'List of database tables' }, async (uri) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
+            const tables = state?.database?.tables ?? [];
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(tables, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query('INFO FOR DB;');
+            const info = result;
+            const tables = info?.[0]?.result?.tables ?? info?.[0]?.tables ?? {};
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(Object.keys(tables), null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.resource('table-data', new ResourceTemplate('sp00ky://tables/{tableName}', { list: undefined }), { description: 'Contents of a specific database table' }, async (uri, variables) => {
+        const tableName = variables.tableName;
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.GET_TABLE_DATA, { tableName });
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query(`SELECT * FROM \`${tableName}\` LIMIT 100;`);
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.resource('queries', 'sp00ky://queries', { description: 'Active live queries' }, async (uri) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
+            const queries = state?.activeQueries ?? [];
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(queries, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query('SELECT * FROM _00_query;');
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.resource('events', 'sp00ky://events', { description: 'Event history' }, async (uri) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
+            const events = state?.eventsHistory ?? [];
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(events, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query('SELECT * FROM _00_events ORDER BY timestamp DESC LIMIT 50;');
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    return server;
+}

package/devtools-mcp/surreal.d.ts

@@ -0,0 +1,13 @@
+export interface SurrealConfig {
+    url: string;
+    namespace: string;
+    database: string;
+    username: string;
+    password: string;
+}
+export declare class SurrealClient {
+    private config;
+    private authHeader;
+    constructor(config: SurrealConfig);
+    query(surql: string): Promise<unknown[]>;
+}

package/devtools-mcp/surreal.js

@@ -0,0 +1,27 @@
+export class SurrealClient {
+    config;
+    authHeader;
+    constructor(config) {
+        this.config = config;
+        this.authHeader =
+            'Basic ' + Buffer.from(`${config.username}:${config.password}`).toString('base64');
+    }
+    async query(surql) {
+        const res = await fetch(`${this.config.url}/sql`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: this.authHeader,
+                'surreal-ns': this.config.namespace,
+                'surreal-db': this.config.database,
+                Accept: 'application/json',
+            },
+            body: surql,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`SurrealDB query failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+}

package/dist/cli.cjs

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-"use strict";const r=require("child_process"),s=require("./resolve-binary-CFmJcXEj.cjs"),o=s.findBinary(),e=r.spawnSync(o,process.argv.slice(2),{stdio:"inherit"});e.error&&(console.error(`Failed to execute spooky: ${e.error.message}`),process.exit(1));process.exit(e.status??1);
+"use strict";const r=require("child_process"),s=require("./resolve-binary-J8VAJRMF.cjs"),i=s.findBinary(),e=r.spawnSync(i,process.argv.slice(2),{stdio:"inherit"});e.error&&(console.error(`Failed to execute spky: ${e.error.message}`),process.exit(1));process.exit(e.status??1);

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync as e } from "child_process";
-import { f as s } from "./resolve-binary-BYotYL89.js";
+import { f as s } from "./resolve-binary-kH1Jwk0z.js";
 const o = s(), r = e(o, process.argv.slice(2), { stdio: "inherit" });
-r.error && (console.error(`Failed to execute spooky: ${r.error.message}`), process.exit(1));
+r.error && (console.error(`Failed to execute spky: ${r.error.message}`), process.exit(1));
 process.exit(r.status ?? 1);

package/dist/resolve-binary-J8VAJRMF.cjs

@@ -0,0 +1,8 @@
+"use strict";const o=require("os"),e=require("path"),t=require("fs"),g=require("url"),k=require("module");var s=typeof document<"u"?document.currentScript:null;const x=g.fileURLToPath(typeof document>"u"?require("url").pathToFileURL(__filename).href:s&&s.tagName.toUpperCase()==="SCRIPT"&&s.src||new URL("resolve-binary-J8VAJRMF.cjs",document.baseURI).href),c=e.dirname(x),d={"darwin-arm64":"@spooky-sync/cli-darwin-arm64","darwin-x64":"@spooky-sync/cli-darwin-x64","linux-arm64":"@spooky-sync/cli-linux-arm64","linux-x64":"@spooky-sync/cli-linux-x64","win32-x64":"@spooky-sync/cli-win32-x64"};function $(){const r=`${o.platform()}-${o.arch()}`,n=d[r];if(!n)return;const l=o.platform()==="win32"?"spky.exe":"spky";try{const i=k.createRequire(typeof document>"u"?require("url").pathToFileURL(__filename).href:s&&s.tagName.toUpperCase()==="SCRIPT"&&s.src||new URL("resolve-binary-J8VAJRMF.cjs",document.baseURI).href).resolve(`${n}/package.json`);return e.resolve(e.dirname(i),l)}catch{return}}function w(){const r=o.platform()==="win32"?"spky.exe":"spky",n=$();if(n&&t.existsSync(n))return n;const l=[e.resolve(c,"../../../target/release",r),e.resolve(c,"../target/release",r),e.resolve(c,"../../../target/debug",r),e.resolve(c,"../target/debug",r)],u=l.filter(a=>t.existsSync(a));if(u.length>0)return u.sort((a,h)=>t.statSync(h).mtimeMs-t.statSync(a).mtimeMs),u[0];const i=e.resolve(c,"..",r);if(t.existsSync(i))return i;const p=e.resolve(process.cwd(),r);if(t.existsSync(p))return p;const m=`${o.platform()}-${o.arch()}`,y=d[m],f=y?`
+Try installing the platform package: npm install ${y}`:`
+Your platform (${m}) is not supported.`;throw new Error(`Could not find spky binary. Checked paths:
+  - Platform package (${y??"none"})
+`+l.map(a=>`  - ${a}
+`).join("")+`  - ${i}
+  - ${p}
+`+f)}exports.findBinary=w;

package/dist/resolve-binary-kH1Jwk0z.js

@@ -0,0 +1,60 @@
+import { platform as m, arch as u } from "os";
+import { dirname as d, resolve as t } from "path";
+import { existsSync as c, statSync as f } from "fs";
+import { fileURLToPath as h } from "url";
+import { createRequire as w } from "module";
+const $ = h(import.meta.url), i = d($), k = {
+  "darwin-arm64": "@spooky-sync/cli-darwin-arm64",
+  "darwin-x64": "@spooky-sync/cli-darwin-x64",
+  "linux-arm64": "@spooky-sync/cli-linux-arm64",
+  "linux-x64": "@spooky-sync/cli-linux-x64",
+  "win32-x64": "@spooky-sync/cli-win32-x64"
+};
+function P() {
+  const r = `${m()}-${u()}`, n = k[r];
+  if (!n) return;
+  const a = m() === "win32" ? "spky.exe" : "spky";
+  try {
+    const e = w(import.meta.url).resolve(`${n}/package.json`);
+    return t(d(e), a);
+  } catch {
+    return;
+  }
+}
+function B() {
+  const r = m() === "win32" ? "spky.exe" : "spky", n = P();
+  if (n && c(n))
+    return n;
+  const a = [
+    t(i, "../../../target/release", r),
+    // workspace release
+    t(i, "../target/release", r),
+    // per-package release
+    t(i, "../../../target/debug", r),
+    // workspace debug
+    t(i, "../target/debug", r)
+    // per-package debug
+  ], s = a.filter((o) => c(o));
+  if (s.length > 0)
+    return s.sort((o, x) => f(x).mtimeMs - f(o).mtimeMs), s[0];
+  const e = t(i, "..", r);
+  if (c(e))
+    return e;
+  const p = t(process.cwd(), r);
+  if (c(p))
+    return p;
+  const y = `${m()}-${u()}`, l = k[y], g = l ? `
+Try installing the platform package: npm install ${l}` : `
+Your platform (${y}) is not supported.`;
+  throw new Error(
+    `Could not find spky binary. Checked paths:
+  - Platform package (${l ?? "none"})
+` + a.map((o) => `  - ${o}
+`).join("") + `  - ${e}
+  - ${p}
+` + g
+  );
+}
+export {
+  B as f
+};

package/dist/resolve-binary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-binary.d.ts","sourceRoot":"","sources":["../src/resolve-binary.ts"],"names":[],"mappings":"AAiCA,wBAAgB,UAAU,IAAI,MAAM,CAyCnC"}
+{"version":3,"file":"resolve-binary.d.ts","sourceRoot":"","sources":["../src/resolve-binary.ts"],"names":[],"mappings":"AAiCA,wBAAgB,UAAU,IAAI,MAAM,CAuDnC"}

package/dist/syncgen.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("child_process"),a=require("util"),i=require("./resolve-binary-CFmJcXEj.cjs"),d=a.promisify(t.execFile);async function f(e){const n=i.findBinary(),r=[];r.push("--input",e.input),r.push("--output",e.output),e.format&&r.push("--format",e.format),e.pretty&&r.push("--pretty"),e.all&&r.push("--all"),e.noHeader&&r.push("--no-header"),e.append&&r.push("--append",e.append),e.modulesDir&&r.push("--modules-dir",e.modulesDir),e.mode&&r.push("--mode",e.mode),e.endpoint&&r.push("--endpoint",e.endpoint),e.secret&&r.push("--secret",e.secret),e.config&&r.push("--config",e.config);try{const{stdout:u,stderr:c}=await d(n,r);return c&&console.error(c),u}catch(u){throw new Error(`Syncgen failed: ${u.message}`)}}exports.runSyncgen=f;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("child_process"),a=require("util"),i=require("./resolve-binary-J8VAJRMF.cjs"),d=a.promisify(t.execFile);async function f(e){const n=i.findBinary(),r=[];r.push("--input",e.input),r.push("--output",e.output),e.format&&r.push("--format",e.format),e.pretty&&r.push("--pretty"),e.all&&r.push("--all"),e.noHeader&&r.push("--no-header"),e.append&&r.push("--append",e.append),e.modulesDir&&r.push("--modules-dir",e.modulesDir),e.mode&&r.push("--mode",e.mode),e.endpoint&&r.push("--endpoint",e.endpoint),e.secret&&r.push("--secret",e.secret),e.config&&r.push("--config",e.config);try{const{stdout:u,stderr:c}=await d(n,r);return c&&console.error(c),u}catch(u){throw new Error(`Syncgen failed: ${u.message}`,{cause:u})}}exports.runSyncgen=f;

package/dist/syncgen.js

@@ -1,17 +1,17 @@
 import { execFile as c } from "child_process";
 import { promisify as d } from "util";
-import { f as t } from "./resolve-binary-BYotYL89.js";
+import { f as t } from "./resolve-binary-kH1Jwk0z.js";
 const i = d(c);
-async function p(e) {
+async function s(e) {
   const a = t(), r = [];
   r.push("--input", e.input), r.push("--output", e.output), e.format && r.push("--format", e.format), e.pretty && r.push("--pretty"), e.all && r.push("--all"), e.noHeader && r.push("--no-header"), e.append && r.push("--append", e.append), e.modulesDir && r.push("--modules-dir", e.modulesDir), e.mode && r.push("--mode", e.mode), e.endpoint && r.push("--endpoint", e.endpoint), e.secret && r.push("--secret", e.secret), e.config && r.push("--config", e.config);
   try {
-    const { stdout: f, stderr: u } = await i(a, r);
-    return u && console.error(u), f;
-  } catch (f) {
-    throw new Error(`Syncgen failed: ${f.message}`);
+    const { stdout: u, stderr: f } = await i(a, r);
+    return f && console.error(f), u;
+  } catch (u) {
+    throw new Error(`Syncgen failed: ${u.message}`, { cause: u });
   }
 }
 export {
-  p as runSyncgen
+  s as runSyncgen
 };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@spooky-sync/cli",
-  "version": "0.0.1-canary.21",
+  "version": "0.0.1-canary.211",
   "description": "Generate TypeScript/Dart types from SurrealDB schema files",
   "type": "module",
   "main": "./dist/syncgen.cjs",
   "module": "./dist/syncgen.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "spooky": "./dist/cli.js"
+    "spky": "./dist/cli.js"
   },
   "exports": {
     ".": {
@@ -17,15 +17,20 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "devtools-mcp",
+    "templates/cookbook",
+    "AGENTS.md"
   ],
   "scripts": {
     "dev": "vite",
+    "dev:build": "cargo build -p sp00ky-cli",
     "build:rust": "cargo build --release",
     "build:vite": "vite build",
     "build:types": "tsc --emitDeclarationOnly --declaration --declarationDir dist",
+    "build:devtools-mcp": "cd ../devtools-mcp && npm run build && cp -r dist ../cli/devtools-mcp",
     "build:js": "npm run build:vite && npm run build:types",
-    "build": "npm run build:rust && npm run build:js",
+    "build": "npm run build:rust && npm run build:devtools-mcp && npm run build:js",
     "preview": "vite preview",
     "test": "vitest",
     "lint": "eslint src",
@@ -42,7 +47,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/mono424/spooky.git",
+    "url": "https://github.com/mono424/sp00ky.git",
     "directory": "apps/cli"
   },
   "publishConfig": {
@@ -56,10 +61,10 @@
     "vitest": "^1.0.0"
   },
   "optionalDependencies": {
-    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.21",
-    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.21",
-    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.21",
-    "@spooky-sync/cli-linux-x64": "0.0.1-canary.21",
-    "@spooky-sync/cli-win32-x64": "0.0.1-canary.21"
+    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.211",
+    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.211",
+    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.211",
+    "@spooky-sync/cli-linux-x64": "0.0.1-canary.211",
+    "@spooky-sync/cli-win32-x64": "0.0.1-canary.211"
   }
 }

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>
+  );
+}