@ggui-ai/protocol-conformance 0.1.0-rc.1

package/dist/ws-transport.js

@@ -0,0 +1,135 @@
+/**
+ * Minimal WebSocket transport for the conformance runner.
+ *
+ * Opens a live-channel connection to a ggui-protocol server (SPEC §12.2),
+ * sends subscribe + action frames verbatim, and exposes an async
+ * `observe()` that collects inbound frames into a buffer for the
+ * matcher.
+ *
+ * Scope discipline: this file is the `kind: 'ws'` arm of
+ * `TransportConfig`. Post-v1.1 transports (stdio MCP, HTTP long-poll)
+ * land as sibling modules with the same `Transport` shape. The
+ * transport is NOT a full MCP client — it does not try to be
+ * compatible with the MCP SDK, and it does not implement stack
+ * management. The kit runs against an already-provisioned session
+ * (the host's `create-session` setup step ran first) and treats the
+ * wire as opaque after that.
+ *
+ * Auth:
+ *   - `bearer` token → `Authorization: Bearer <token>` header on
+ *     the upgrade request.
+ *   - `session-cookie` → `Cookie: <cookie>` header.
+ */
+import WebSocket from 'ws';
+/**
+ * Open a WS transport against `config.url`, wait for the socket to
+ * reach `OPEN` state, and return the transport handle. Throws if the
+ * socket errors or closes before reaching OPEN.
+ */
+export async function openWsTransport(config) {
+    const headers = authHeaders(config.auth);
+    const socket = new WebSocket(config.url, { headers });
+    const buffer = [];
+    let flushWaiter = null;
+    socket.on('message', (raw) => {
+        const text = raw.toString('utf8');
+        const parsed = safeParse(text);
+        const frame = parsed.ok === true
+            ? { kind: 'frame', raw: text, parsed: parsed.value }
+            : { kind: 'unparseable', raw: text, error: parsed.error };
+        buffer.push(frame);
+        // Fire any pending observer synchronously so predicate-driven
+        // early-return works without a polling loop.
+        const waiter = flushWaiter;
+        if (waiter !== null) {
+            flushWaiter = null;
+            waiter(frame);
+        }
+    });
+    await new Promise((done, fail) => {
+        const onOpen = () => {
+            socket.off('error', onError);
+            socket.off('close', onClose);
+            done();
+        };
+        const onError = (err) => {
+            socket.off('open', onOpen);
+            socket.off('close', onClose);
+            fail(err);
+        };
+        const onClose = (code, reason) => {
+            socket.off('open', onOpen);
+            socket.off('error', onError);
+            fail(new Error(`protocol-conformance: ws closed before open — code=${code} reason=${reason.toString('utf8')}`));
+        };
+        socket.once('open', onOpen);
+        socket.once('error', onError);
+        socket.once('close', onClose);
+    });
+    return {
+        send(frame) {
+            socket.send(JSON.stringify(frame));
+        },
+        async observe({ timeoutMs, predicate }) {
+            // Drain any already-buffered frames first; the timeout only
+            // bounds the wait for NEW frames.
+            if (predicate !== undefined) {
+                const existing = buffer.find((f) => predicate(f));
+                if (existing !== undefined)
+                    return snapshot(buffer);
+            }
+            await new Promise((done) => {
+                const timer = setTimeout(() => {
+                    flushWaiter = null;
+                    done();
+                }, timeoutMs);
+                const onFrame = (frame) => {
+                    if (predicate !== undefined && predicate(frame)) {
+                        clearTimeout(timer);
+                        done();
+                        return;
+                    }
+                    flushWaiter = onFrame;
+                };
+                flushWaiter = onFrame;
+            });
+            return snapshot(buffer);
+        },
+        async close() {
+            if (socket.readyState === WebSocket.CLOSED ||
+                socket.readyState === WebSocket.CLOSING) {
+                return;
+            }
+            await new Promise((done) => {
+                socket.once('close', () => done());
+                socket.close();
+            });
+        },
+    };
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function authHeaders(auth) {
+    switch (auth.kind) {
+        case 'bearer':
+            return { Authorization: `Bearer ${auth.token}` };
+        case 'session-cookie':
+            return { Cookie: auth.cookie };
+    }
+}
+function safeParse(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return { ok: false, error: 'frame is not a JSON object' };
+        }
+        return { ok: true, value: parsed };
+    }
+    catch (err) {
+        return { ok: false, error: String(err.message ?? err) };
+    }
+}
+function snapshot(buffer) {
+    return buffer.slice();
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@ggui-ai/protocol-conformance",
+  "version": "0.1.0-rc.1",
+  "description": "Conformance test kit for the ggui protocol. Drives a behavioral fixture catalog against a live implementation over WebSocket, plus three pure-function catalogs (schema, registration, resolution) for the gadget obligations, and reports a scorecard-style pass / fail / skip. MCP builders adopt this kit to prove their implementation is protocol-conformant.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ggui",
+    "mcp",
+    "protocol",
+    "conformance",
+    "test-kit"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ggui-protocol-conformance": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./fixtures": {
+      "types": "./dist/fixtures/index.d.ts",
+      "import": "./dist/fixtures/index.js",
+      "default": "./dist/fixtures/index.js"
+    },
+    "./schema-conformance": {
+      "types": "./dist/schema-conformance/index.d.ts",
+      "import": "./dist/schema-conformance/index.js",
+      "default": "./dist/schema-conformance/index.js"
+    },
+    "./registration-conformance": {
+      "types": "./dist/registration-conformance/index.d.ts",
+      "import": "./dist/registration-conformance/index.js",
+      "default": "./dist/registration-conformance/index.js"
+    },
+    "./resolution-conformance": {
+      "types": "./dist/resolution-conformance/index.d.ts",
+      "import": "./dist/resolution-conformance/index.js",
+      "default": "./dist/resolution-conformance/index.js"
+    }
+  },
+  "dependencies": {
+    "ws": "^8.20.1",
+    "@ggui-ai/protocol": "0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/protocol-conformance"
+  },
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/protocol-conformance",
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node ../scripts/fix-esm-imports.mjs dist && chmod +x dist/cli.js",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}