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

package/AGENTS.md

@@ -0,0 +1,138 @@
+# `@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, and print the scheduler's own drift verdict (`/health/snapshot` `drift`). `--fix` re-clones the scheduler replica when its counts are off, otherwise forces every SSP to re-bootstrap. The scheduler runs the same count check itself at startup and after each snapshot drain and auto-reclones by default (`SPKY_DRIFT_AUTO_RECLONE`).
+- **`spky lint`** — validate `sp00ky.yml` and referenced files exist.
+- **`spky dev [--apply-migrations] [--clean] [--verbose]`** — boots a local SurrealDB + SSP + scheduler stack via Docker. `--clean` wipes SSP/scheduler state but preserves user data in SurrealDB. Startup renders as step lines via `src/ui.rs` (indicatif/console; plain lines when not a TTY); after "ready" only ERROR/crash-looking lines (infra and app streams) show unless `--verbose` / `SPKY_VERBOSE=1`. A bare `logLevel` is scoped to sp00ky crates by `backend::scoped_rust_log`.
+- **`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.
+- `-- @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.
+
+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
+
+-- @opaque
+DEFINE FIELD preview_png ON TABLE thread TYPE option<bytes>;
+
+-- @nosync
+DEFINE TABLE audit_log SCHEMALESS;
+```
+
+A descriptor must sit directly above its statement (no blank line between). One that attaches to nothing is warned about, not silently dropped (`annotations::warn_unattached_annotations`).
+
+## Docker dev apps (`type: docker`)
+
+Besides `backend`/`frontend` apps, `sp00ky.yml` can declare `type: docker` apps —
+containers `spky dev` runs alongside SurrealDB/SSP/scheduler on the
+`sp00ky-dev-net` network (each reachable from the others by its app **name**, via
+a `--network-alias`). Use `scope: devOnly` for local-only sidecars: never
+deployed, and they skip the backend spec/method/deploy validation.
+
+Fields:
+
+- `image` (required) — image to run, e.g. `bluenviron/mediamtx:latest` or `golang:1.22`.
+- `ports` — published to the host: `[1935, "8189/udp", "3000:8080"]` (a bare value maps the same port host:container; `/udp` suffix preserved).
+- `args` — appended after the image (the container command), e.g. `["go", "run", "."]`.
+- `env` — same forms as other apps (inline map / dotenv path / vault). User values **override** the auto-injected `SPKY_*` vars. `${PROJECT_DIR}` (the absolute dir of `sp00ky.yml`) is expanded in values.
+- `volumes` — bind/volume mounts (`-v`), e.g. `["/var/run/docker.sock:/var/run/docker.sock", "${PROJECT_DIR}/../..:/src", "gomod:/go"]`. `${PROJECT_DIR}` is expanded in the host portion (Docker normalizes `..`).
+- `workdir` — working directory inside the container (`-w`).
+- `dependsOn` — names of other docker apps that must be **ready** before this one starts; `spky dev` starts apps in dependency order. Validated at config load — an unknown name, a self-dependency, or a **cycle** is a hard error (`spky lint` reports it).
+- `healthcheck` — an HTTP path (e.g. `/health`) polled on the app's first published host port until it returns 200. Lets a dependency signal real readiness so `dependsOn` waits for "up", not just "container started". Without it, a dependency counts as ready once its container is running.
+
+Containers run as `sp00ky-dev-<name>` with `--rm` and are killed on Ctrl-C.
+`dependsOn`/`healthcheck` are `spky dev` concerns; the cloud deploy path ignores
+them (and `cloudOnly` docker apps are skipped by `spky dev`).
+
+Example — a relay built from source via `go run`, and a publisher that waits for it:
+```yaml
+apps:
+  relay:
+    type: docker
+    scope: devOnly
+    image: golang:1.22
+    workdir: /src/apps/relay
+    args: ["go", "run", "."]
+    ports: [3670]
+    healthcheck: /health
+    volumes:
+      - "${PROJECT_DIR}/../..:/src"
+      - "gomod:/go"
+  publisher:
+    type: docker
+    scope: devOnly
+    image: golang:1.22
+    workdir: /src/apps/publisher
+    args: ["go", "run", "."]
+    dependsOn: [relay]          # started only after relay's /health returns 200
+    volumes:
+      - "${PROJECT_DIR}/../..:/src"
+      - "gomod:/go"
+```
+
+## 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/README.md

@@ -1,4 +1,4 @@
-# Spooky CLI
+# Sp00ky CLI
 
 Generate TypeScript and Dart types from SurrealDB schema files.
 
@@ -18,28 +18,28 @@ This package wraps a Rust-based code generator that parses SurrealDB `.surql` sc
 
 ```bash
 # Generate TypeScript types
-spooky --input schema.surql --output types.ts
+spky --input schema.surql --output types.ts
 
 # Generate Dart types
-spooky --input schema.surql --output types.dart
+spky --input schema.surql --output types.dart
 
 # Generate JSON Schema
-spooky --input schema.surql --output schema.json
+spky --input schema.surql --output schema.json
 
 # Generate all formats at once
-spooky --input schema.surql --output output --all
+spky --input schema.surql --output output --all
 
 # Specify format explicitly
-spooky --input schema.surql --output output.ts --format typescript
+spky --input schema.surql --output output.ts --format typescript
 ```
 
 ### Programmatic API
 
 ```typescript
-import { runSpooky } from 'spooky-cli';
+import { runSp00ky } from 'sp00ky-cli';
 
 // Generate types
-const output = await runSpooky({
+const output = await runSp00ky({
   input: 'path/to/schema.surql',
   output: 'path/to/output.ts',
   format: 'typescript', // or 'dart', 'json'
@@ -95,7 +95,7 @@ cli/
 
 ## How It Works
 
-1. The Rust binary (`spooky`) parses SurrealDB schema files and generates JSON Schema
+1. The Rust binary (`spky`) parses SurrealDB schema files and generates JSON Schema
 2. For TypeScript/Dart output, it uses `quicktype` to convert JSON Schema to the target language
 3. The TypeScript wrapper (`src/index.ts`) spawns the Rust binary as a child process
 4. Vite bundles the TypeScript wrapper for distribution

package/devtools-mcp/bridge.d.ts

@@ -0,0 +1,23 @@
+interface ConnectedTab {
+    tabId: number;
+    url?: string;
+    title?: string;
+}
+export declare class Bridge {
+    private wss;
+    private extensionSocket;
+    private connectedTabs;
+    private pendingRequests;
+    private requestCounter;
+    private pingInterval;
+    get isConnected(): boolean;
+    getConnectedTabs(): ConnectedTab[];
+    start(): Promise<void>;
+    private startPing;
+    private stopPing;
+    private handleMessage;
+    request(method: string, params?: Record<string, unknown>, tabId?: number): Promise<unknown>;
+    private getDefaultTabId;
+    stop(): Promise<void>;
+}
+export {};

package/devtools-mcp/bridge.js

@@ -0,0 +1,155 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { isBridgeResponse, isBridgeNotification, BRIDGE_PORT, } from './protocol.js';
+const REQUEST_TIMEOUT_MS = 10_000;
+export class Bridge {
+    wss = null;
+    extensionSocket = null;
+    connectedTabs = new Map();
+    pendingRequests = new Map();
+    requestCounter = 0;
+    pingInterval = null;
+    get isConnected() {
+        return this.extensionSocket?.readyState === WebSocket.OPEN;
+    }
+    getConnectedTabs() {
+        return Array.from(this.connectedTabs.values());
+    }
+    start() {
+        const port = Number.parseInt(process.env.SP00KY_MCP_PORT || '', 10) || BRIDGE_PORT;
+        return new Promise((resolve, reject) => {
+            this.wss = new WebSocketServer({ host: '127.0.0.1', port }, () => {
+                process.stderr.write(`[sp00ky-mcp] Bridge listening on ws://127.0.0.1:${port}\n`);
+                resolve();
+            });
+            this.wss.on('error', (err) => {
+                process.stderr.write(`[sp00ky-mcp] Bridge error: ${err.message}\n`);
+                reject(err);
+            });
+            this.wss.on('connection', (ws) => {
+                process.stderr.write('[sp00ky-mcp] Extension connected\n');
+                // Only allow one extension connection at a time
+                if (this.extensionSocket) {
+                    this.extensionSocket.close();
+                }
+                this.extensionSocket = ws;
+                // Start keepalive pings
+                this.startPing(ws);
+                ws.on('message', (data) => {
+                    try {
+                        const msg = JSON.parse(data.toString());
+                        this.handleMessage(msg);
+                    }
+                    catch (err) {
+                        process.stderr.write(`[sp00ky-mcp] Bad message: ${err}\n`);
+                    }
+                });
+                ws.on('close', () => {
+                    process.stderr.write('[sp00ky-mcp] Extension disconnected\n');
+                    if (this.extensionSocket === ws) {
+                        this.extensionSocket = null;
+                        this.connectedTabs.clear();
+                        this.stopPing();
+                        // Reject all pending requests
+                        for (const [id, pending] of this.pendingRequests) {
+                            pending.reject(new Error('Extension disconnected'));
+                            clearTimeout(pending.timer);
+                            this.pendingRequests.delete(id);
+                        }
+                    }
+                });
+                ws.on('error', (err) => {
+                    process.stderr.write(`[sp00ky-mcp] Socket error: ${err.message}\n`);
+                });
+            });
+        });
+    }
+    startPing(ws) {
+        this.stopPing();
+        this.pingInterval = setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.ping();
+            }
+        }, 20_000);
+    }
+    stopPing() {
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+    }
+    handleMessage(msg) {
+        // Handle response to a pending request
+        if (isBridgeResponse(msg)) {
+            const pending = this.pendingRequests.get(msg.id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(msg.id);
+                if (msg.error) {
+                    pending.reject(new Error(msg.error.message));
+                }
+                else {
+                    pending.resolve(msg.result);
+                }
+            }
+            return;
+        }
+        // Handle notifications from extension
+        if (isBridgeNotification(msg)) {
+            if (msg.method === 'tabsChanged') {
+                this.connectedTabs.clear();
+                const tabs = msg.params.tabs;
+                for (const tab of tabs) {
+                    this.connectedTabs.set(tab.tabId, tab);
+                }
+            }
+            return;
+        }
+    }
+    async request(method, params = {}, tabId) {
+        if (!this.extensionSocket || this.extensionSocket.readyState !== WebSocket.OPEN) {
+            throw new Error('No extension connected. Make sure the Sp00ky DevTools extension is running and has a page with Sp00ky open.');
+        }
+        const id = `mcp-${++this.requestCounter}`;
+        const resolvedTabId = tabId ?? this.getDefaultTabId();
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+            ...(resolvedTabId !== undefined ? { tabId: resolvedTabId } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms: ${method}`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            // oxlint-disable-next-line no-non-null-assertion
+            this.extensionSocket.send(JSON.stringify(request));
+        });
+    }
+    getDefaultTabId() {
+        const tabs = this.getConnectedTabs();
+        return tabs.length > 0 ? tabs[0].tabId : undefined;
+    }
+    async stop() {
+        this.stopPing();
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Bridge shutting down'));
+            this.pendingRequests.delete(id);
+        }
+        if (this.extensionSocket) {
+            this.extensionSocket.close();
+            this.extensionSocket = null;
+        }
+        return new Promise((resolve) => {
+            if (this.wss) {
+                this.wss.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}

package/devtools-mcp/dist/bridge.d.ts

@@ -0,0 +1,23 @@
+interface ConnectedTab {
+    tabId: number;
+    url?: string;
+    title?: string;
+}
+export declare class Bridge {
+    private wss;
+    private extensionSocket;
+    private connectedTabs;
+    private pendingRequests;
+    private requestCounter;
+    private pingInterval;
+    get isConnected(): boolean;
+    getConnectedTabs(): ConnectedTab[];
+    start(): Promise<void>;
+    private startPing;
+    private stopPing;
+    private handleMessage;
+    request(method: string, params?: Record<string, unknown>, tabId?: number): Promise<unknown>;
+    private getDefaultTabId;
+    stop(): Promise<void>;
+}
+export {};

package/devtools-mcp/dist/bridge.js

@@ -0,0 +1,155 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { isBridgeResponse, isBridgeNotification, BRIDGE_PORT, } from './protocol.js';
+const REQUEST_TIMEOUT_MS = 10_000;
+export class Bridge {
+    wss = null;
+    extensionSocket = null;
+    connectedTabs = new Map();
+    pendingRequests = new Map();
+    requestCounter = 0;
+    pingInterval = null;
+    get isConnected() {
+        return this.extensionSocket?.readyState === WebSocket.OPEN;
+    }
+    getConnectedTabs() {
+        return Array.from(this.connectedTabs.values());
+    }
+    start() {
+        const port = Number.parseInt(process.env.SP00KY_MCP_PORT || '', 10) || BRIDGE_PORT;
+        return new Promise((resolve, reject) => {
+            this.wss = new WebSocketServer({ host: '127.0.0.1', port }, () => {
+                process.stderr.write(`[sp00ky-mcp] Bridge listening on ws://127.0.0.1:${port}\n`);
+                resolve();
+            });
+            this.wss.on('error', (err) => {
+                process.stderr.write(`[sp00ky-mcp] Bridge error: ${err.message}\n`);
+                reject(err);
+            });
+            this.wss.on('connection', (ws) => {
+                process.stderr.write('[sp00ky-mcp] Extension connected\n');
+                // Only allow one extension connection at a time
+                if (this.extensionSocket) {
+                    this.extensionSocket.close();
+                }
+                this.extensionSocket = ws;
+                // Start keepalive pings
+                this.startPing(ws);
+                ws.on('message', (data) => {
+                    try {
+                        const msg = JSON.parse(data.toString());
+                        this.handleMessage(msg);
+                    }
+                    catch (err) {
+                        process.stderr.write(`[sp00ky-mcp] Bad message: ${err}\n`);
+                    }
+                });
+                ws.on('close', () => {
+                    process.stderr.write('[sp00ky-mcp] Extension disconnected\n');
+                    if (this.extensionSocket === ws) {
+                        this.extensionSocket = null;
+                        this.connectedTabs.clear();
+                        this.stopPing();
+                        // Reject all pending requests
+                        for (const [id, pending] of this.pendingRequests) {
+                            pending.reject(new Error('Extension disconnected'));
+                            clearTimeout(pending.timer);
+                            this.pendingRequests.delete(id);
+                        }
+                    }
+                });
+                ws.on('error', (err) => {
+                    process.stderr.write(`[sp00ky-mcp] Socket error: ${err.message}\n`);
+                });
+            });
+        });
+    }
+    startPing(ws) {
+        this.stopPing();
+        this.pingInterval = setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.ping();
+            }
+        }, 20_000);
+    }
+    stopPing() {
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+    }
+    handleMessage(msg) {
+        // Handle response to a pending request
+        if (isBridgeResponse(msg)) {
+            const pending = this.pendingRequests.get(msg.id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(msg.id);
+                if (msg.error) {
+                    pending.reject(new Error(msg.error.message));
+                }
+                else {
+                    pending.resolve(msg.result);
+                }
+            }
+            return;
+        }
+        // Handle notifications from extension
+        if (isBridgeNotification(msg)) {
+            if (msg.method === 'tabsChanged') {
+                this.connectedTabs.clear();
+                const tabs = msg.params.tabs;
+                for (const tab of tabs) {
+                    this.connectedTabs.set(tab.tabId, tab);
+                }
+            }
+            return;
+        }
+    }
+    async request(method, params = {}, tabId) {
+        if (!this.extensionSocket || this.extensionSocket.readyState !== WebSocket.OPEN) {
+            throw new Error('No extension connected. Make sure the Sp00ky DevTools extension is running and has a page with Sp00ky open.');
+        }
+        const id = `mcp-${++this.requestCounter}`;
+        const resolvedTabId = tabId ?? this.getDefaultTabId();
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+            ...(resolvedTabId !== undefined ? { tabId: resolvedTabId } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms: ${method}`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            // oxlint-disable-next-line no-non-null-assertion
+            this.extensionSocket.send(JSON.stringify(request));
+        });
+    }
+    getDefaultTabId() {
+        const tabs = this.getConnectedTabs();
+        return tabs.length > 0 ? tabs[0].tabId : undefined;
+    }
+    async stop() {
+        this.stopPing();
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Bridge shutting down'));
+            this.pendingRequests.delete(id);
+        }
+        if (this.extensionSocket) {
+            this.extensionSocket.close();
+            this.extensionSocket = null;
+        }
+        return new Promise((resolve) => {
+            if (this.wss) {
+                this.wss.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}

package/devtools-mcp/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/devtools-mcp/dist/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Bridge } from './bridge.js';
+import { SurrealClient } from './surreal.js';
+import { createServer } from './server.js';
+async function main() {
+    const bridge = new Bridge();
+    await bridge.start();
+    const surreal = process.env.SURREAL_URL
+        ? new SurrealClient({
+            url: process.env.SURREAL_URL,
+            namespace: process.env.SURREAL_NS ?? 'main',
+            database: process.env.SURREAL_DB ?? 'main',
+            username: process.env.SURREAL_USER ?? 'root',
+            password: process.env.SURREAL_PASS ?? 'root',
+        })
+        : null;
+    if (surreal) {
+        process.stderr.write(`[sp00ky-mcp] Direct DB mode enabled (${process.env.SURREAL_URL})\n`);
+    }
+    const server = createServer(bridge, surreal);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[sp00ky-mcp] MCP server running on stdio\n');
+    // Graceful shutdown
+    const cleanup = async () => {
+        process.stderr.write('[sp00ky-mcp] Shutting down...\n');
+        await bridge.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+}
+main().catch((err) => {
+    process.stderr.write(`[sp00ky-mcp] Fatal error: ${err.message}\n`);
+    process.exit(1);
+});

package/devtools-mcp/dist/protocol.d.ts

@@ -0,0 +1,35 @@
+export interface BridgeRequest {
+    jsonrpc: '2.0';
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+    tabId?: number;
+}
+export interface BridgeResponse {
+    jsonrpc: '2.0';
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface BridgeNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params: Record<string, unknown>;
+}
+export type BridgeMessage = BridgeRequest | BridgeResponse | BridgeNotification;
+export declare const BRIDGE_METHODS: {
+    readonly GET_STATE: "getState";
+    readonly RUN_QUERY: "runQuery";
+    readonly GET_TABLE_DATA: "getTableData";
+    readonly GET_QUERY_ROWS: "getQueryRows";
+    readonly UPDATE_TABLE_ROW: "updateTableRow";
+    readonly DELETE_TABLE_ROW: "deleteTableRow";
+    readonly CLEAR_HISTORY: "clearHistory";
+};
+export declare const BRIDGE_PORT = 9315;
+export declare function isBridgeResponse(msg: unknown): msg is BridgeResponse;
+export declare function isBridgeRequest(msg: unknown): msg is BridgeRequest;
+export declare function isBridgeNotification(msg: unknown): msg is BridgeNotification;

package/devtools-mcp/dist/protocol.js

@@ -0,0 +1,38 @@
+// Shared message types for MCP Server <-> Chrome Extension bridge (JSON-RPC 2.0 style)
+// Methods the MCP server can call on the extension
+export const BRIDGE_METHODS = {
+    GET_STATE: 'getState',
+    RUN_QUERY: 'runQuery',
+    GET_TABLE_DATA: 'getTableData',
+    GET_QUERY_ROWS: 'getQueryRows',
+    UPDATE_TABLE_ROW: 'updateTableRow',
+    DELETE_TABLE_ROW: 'deleteTableRow',
+    CLEAR_HISTORY: 'clearHistory',
+};
+export const BRIDGE_PORT = 9315;
+export function isBridgeResponse(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'jsonrpc' in msg &&
+        msg.jsonrpc === '2.0' &&
+        'id' in msg &&
+        ('result' in msg || 'error' in msg));
+}
+export function isBridgeRequest(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'jsonrpc' in msg &&
+        msg.jsonrpc === '2.0' &&
+        'method' in msg &&
+        'id' in msg &&
+        !('result' in msg) &&
+        !('error' in msg));
+}
+export function isBridgeNotification(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'jsonrpc' in msg &&
+        msg.jsonrpc === '2.0' &&
+        'method' in msg &&
+        !('id' in msg));
+}

package/devtools-mcp/dist/server.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Bridge } from './bridge.js';
+import type { SurrealClient } from './surreal.js';
+export declare function createServer(bridge: Bridge, surreal?: SurrealClient | null): McpServer;