@biomate/connect 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @biomate/connect
+
+> One-line installer that wires BioMate AI into Claude Code, Claude Desktop, Cursor, OpenAI Codex, ChatGPT, and Open Claw (WeChat).
+
+Real bioinformatics — `WGS variant-calling pipeline`, CryoSPARC, AlphaFold, ADMET screens, PBPK — runs from your favorite AI coding assistant. No SaaS lock-in: tokens are stored locally and revocable per-surface from your BioMate account.
+
+## Install
+
+```bash
+# Connect Claude Code
+npx @biomate/connect claude-code
+
+# Connect Cursor
+npx @biomate/connect cursor
+
+# Connect Codex CLI
+npx @biomate/connect codex
+```
+
+That's it. The CLI opens your browser, runs OAuth 2.1 + PKCE against `https://biomate.ai`, writes the MCP server entry into the right host config file, and stashes a refresh token in your OS keychain.
+
+## Supported surfaces
+
+| Surface | Install command | Config file written |
+|---|---|---|
+| Claude Code | `npx @biomate/connect claude-code` | `~/.claude.json` |
+| Claude Desktop | `npx @biomate/connect claude-desktop` | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Cursor | `npx @biomate/connect cursor` | `~/.cursor/mcp.json` |
+| Codex CLI | `npx @biomate/connect codex` | `~/.codex/config.toml` |
+| ChatGPT | `npx @biomate/connect chatgpt` | (Custom GPT — instructions printed) |
+| Open Claw | `npx @biomate/connect open-claw` | (hosted webhook — account linked) |
+
+## What you get
+
+After connecting, your AI assistant has access to BioMate's 14-tool MCP surface:
+
+- **`biomate_session`** — natural-language goal → streaming workflow run with phase/step/QC/findings events
+- **`search_workflow`** + **`get_workflow_spec`** — discover from 2,455 indexed workflows
+- **`run_workflow`** + **`get_run`** + **`cancel_run`** — fine control
+- **`preview_file`**, **`export_report`**, **`recall_memory`**, **`upload_file`**, **`analyze_results`**, **`explain_error`**, **`query_database`**
+
+## Try it
+
+Open your assistant and paste:
+
+```
+Screen aspirin and caffeine for hERG and CYP3A4 inhibition.
+```
+
+```
+Run RNA-seq differential expression on these FASTQs:
+  s3://biomate-demo/sample_R1.fq.gz, s3://biomate-demo/sample_R2.fq.gz
+Compare treated vs control.
+```
+
+```
+Look up UniProt P04637.
+```
+
+## Privacy & security
+
+- OAuth 2.1 + PKCE; tokens scoped per surface, revocable individually at
+  https://biomate.ai/account/connectors
+- Refresh tokens hashed at rest with HMAC-SHA256
+- Access tokens are 30-minute JWTs; refresh tokens rotate on use (OAuth 2.1 §6.1)
+- No telemetry beyond standard API logs
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/dist/__tests__/configWriters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/configWriters.test.js

@@ -0,0 +1,89 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs_1 = require("fs");
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const configWriters_js_1 = require("../configWriters.js");
+async function tmpDir() {
+    return fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'biomate-test-'));
+}
+(0, vitest_1.describe)('upsertJSON', () => {
+    (0, vitest_1.it)('creates new file with content', async () => {
+        const dir = await tmpDir();
+        const f = path.join(dir, 'a', 'b', 'cfg.json');
+        await (0, configWriters_js_1.upsertJSON)(f, (cfg) => {
+            cfg.mcpServers = { biomate: { command: 'npx', args: [] } };
+            return cfg;
+        });
+        const got = JSON.parse(await fs_1.promises.readFile(f, 'utf8'));
+        (0, vitest_1.expect)(got.mcpServers.biomate.command).toBe('npx');
+    });
+    (0, vitest_1.it)('preserves existing keys', async () => {
+        const dir = await tmpDir();
+        const f = path.join(dir, 'cfg.json');
+        await fs_1.promises.writeFile(f, JSON.stringify({ theme: 'dark', mcpServers: { other: { command: 'foo' } } }));
+        await (0, configWriters_js_1.upsertJSON)(f, (cfg) => {
+            cfg.mcpServers.biomate = { command: 'npx' };
+            return cfg;
+        });
+        const got = JSON.parse(await fs_1.promises.readFile(f, 'utf8'));
+        (0, vitest_1.expect)(got.theme).toBe('dark');
+        (0, vitest_1.expect)(got.mcpServers.other.command).toBe('foo');
+        (0, vitest_1.expect)(got.mcpServers.biomate.command).toBe('npx');
+    });
+});
+(0, vitest_1.describe)('upsertTOML', () => {
+    (0, vitest_1.it)('appends a new biomate block', async () => {
+        const dir = await tmpDir();
+        const f = path.join(dir, 'config.toml');
+        await fs_1.promises.writeFile(f, '[other]\nfoo = "bar"\n');
+        await (0, configWriters_js_1.upsertTOML)(f, '\n[mcp_servers.biomate]\ncommand = "npx"\n');
+        const got = await fs_1.promises.readFile(f, 'utf8');
+        (0, vitest_1.expect)(got).toContain('[other]');
+        (0, vitest_1.expect)(got).toContain('[mcp_servers.biomate]');
+        (0, vitest_1.expect)(got).toContain('command = "npx"');
+    });
+    (0, vitest_1.it)('replaces existing biomate block on re-install', async () => {
+        const dir = await tmpDir();
+        const f = path.join(dir, 'config.toml');
+        await (0, configWriters_js_1.upsertTOML)(f, '\n[mcp_servers.biomate]\ntoken = "old"\n');
+        await (0, configWriters_js_1.upsertTOML)(f, '\n[mcp_servers.biomate]\ntoken = "new"\n');
+        const got = await fs_1.promises.readFile(f, 'utf8');
+        (0, vitest_1.expect)(got).toContain('token = "new"');
+        (0, vitest_1.expect)(got).not.toContain('token = "old"');
+    });
+});

package/dist/__tests__/flow.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Installer end-to-end flow tests.
+ *
+ * Covers TEST_PLAN.md §3.2 (12 cases). Each test spins up a mock OAuth
+ * server (Node http) that mirrors api.biomate.ai's /oauth/authorize and
+ * /oauth/token endpoints, then drives the installer against a tmp HOME so
+ * file writes don't touch the developer's real config.
+ */
+export {};

package/dist/__tests__/flow.test.js

@@ -0,0 +1,291 @@
+"use strict";
+/**
+ * Installer end-to-end flow tests.
+ *
+ * Covers TEST_PLAN.md §3.2 (12 cases). Each test spins up a mock OAuth
+ * server (Node http) that mirrors api.biomate.ai's /oauth/authorize and
+ * /oauth/token endpoints, then drives the installer against a tmp HOME so
+ * file writes don't touch the developer's real config.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const fs_1 = require("fs");
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+// os.homedir() in Node is non-configurable; we can't replace it directly.
+// Instead, mock the entire 'os' module so surfaces.ts gets our stub.
+let __testHome = process.env.HOME ?? '/tmp';
+vitest_1.vi.mock('os', async () => {
+    const actual = await vitest_1.vi.importActual('os');
+    return { ...actual, homedir: () => __testHome };
+});
+const http_1 = require("http");
+const url_1 = require("url");
+// Hold the per-test handler that the mocked `open` will call.
+let __openHandler = null;
+vitest_1.vi.mock('open', () => ({
+    default: async (url) => {
+        if (__openHandler)
+            await __openHandler(typeof url === 'string' ? url : url.toString());
+        return { unref: () => undefined };
+    },
+}));
+const oauth_js_1 = require("../oauth.js");
+const surfaces_js_1 = require("../surfaces.js");
+// Assign each test a unique port to avoid TCP TIME_WAIT collisions across tests.
+let __portCursor = 60000;
+function uniquePort() {
+    return __portCursor++;
+}
+function withPort(s) {
+    return { ...s, callbackPort: uniquePort() };
+}
+function startMockServer() {
+    const behavior = {};
+    let lastVerifier = null;
+    let issuedCodes = new Map();
+    const server = (0, http_1.createServer)(async (req, res) => {
+        const u = new url_1.URL(req.url ?? '/', `http://${req.headers.host}`);
+        if (u.pathname === '/oauth/authorize' && req.method === 'GET') {
+            // The installer never hits /oauth/authorize as an HTTP client — its
+            // browser does. We simulate by auto-redirecting on a different path.
+            res.writeHead(200);
+            res.end('ok');
+            return;
+        }
+        if (u.pathname === '/simulate-callback' && req.method === 'GET') {
+            // Test helper: forwards a code (or error) to the installer's callback port.
+            const code = u.searchParams.get('code');
+            const error = u.searchParams.get('error');
+            const state = u.searchParams.get('state');
+            const port = u.searchParams.get('port');
+            const params = new URLSearchParams();
+            if (code)
+                params.set('code', code);
+            if (error)
+                params.set('error', error);
+            if (state)
+                params.set('state', state);
+            const cbUrl = `http://127.0.0.1:${port}/callback?${params.toString()}`;
+            await fetch(cbUrl).catch(() => { });
+            res.writeHead(200);
+            res.end('forwarded');
+            return;
+        }
+        if (u.pathname === '/oauth/token' && req.method === 'POST') {
+            const body = await readBody(req);
+            const form = new URLSearchParams(body);
+            lastVerifier = form.get('code_verifier');
+            const status = behavior.tokenStatus ?? 200;
+            res.writeHead(status, { 'content-type': 'application/json' });
+            if (status !== 200) {
+                res.end(JSON.stringify({ error: 'invalid_grant', error_description: 'mock' }));
+                return;
+            }
+            res.end(JSON.stringify({
+                access_token: 'mock_access_token',
+                refresh_token: 'mock_refresh_token',
+                token_type: 'Bearer',
+                expires_in: 1800,
+                scope: form.get('scope') ?? 'runs:read runs:write',
+            }));
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                close: () => new Promise((r) => server.close(() => r(undefined))),
+                lastVerifier: () => lastVerifier,
+                behavior,
+            });
+        });
+    });
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/**
+ * Replace `open` with a function that, instead of launching a browser, hits
+ * /simulate-callback on the mock server with the right code + state.
+ */
+function installOpenStub(mockUrl, port, opts) {
+    __openHandler = async (authUrl) => {
+        const u = new url_1.URL(authUrl);
+        const state = opts.stateOverride ?? (u.searchParams.get('state') ?? '');
+        const params = new URLSearchParams({ port: String(port) });
+        if (opts.error)
+            params.set('error', opts.error);
+        else
+            params.set('code', 'mock_code_' + Math.random().toString(36).slice(2));
+        params.set('state', state);
+        await fetch(`${mockUrl}/simulate-callback?${params.toString()}`);
+    };
+}
+(0, vitest_1.describe)('installer end-to-end flow', () => {
+    let mock;
+    let tmpHome;
+    let origHome;
+    (0, vitest_1.beforeEach)(async () => {
+        mock = await startMockServer();
+        tmpHome = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'biomate-flow-'));
+        origHome = process.env.HOME;
+        process.env.HOME = tmpHome;
+        __testHome = tmpHome;
+        process.env.BIOMATE_API_BASE = 'https://mock.api.example';
+    });
+    (0, vitest_1.afterEach)(async () => {
+        __openHandler = null;
+        await mock.close();
+        if (origHome)
+            process.env.HOME = origHome;
+        else
+            delete process.env.HOME;
+        await fs_1.promises.rm(tmpHome, { recursive: true, force: true });
+    });
+    // --- §3.2.1, §3.2.2, §3.2.3, §3.2.4, §3.2.5, §3.2.6, §3.2.7 — per-surface ---
+    (0, vitest_1.it)('§3.2.1 claude-code: writes ~/.claude.json with mcpServers.biomate on fresh machine', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['claude-code']);
+        installOpenStub(mock.url, surface.callbackPort, {});
+        const tokens = await (0, oauth_js_1.runPKCEFlow)(surface, mock.url);
+        await surface.install(tokens.access_token, tokens.refresh_token);
+        const cfg = JSON.parse(await fs_1.promises.readFile(path.join(tmpHome, '.claude.json'), 'utf8'));
+        (0, vitest_1.expect)(cfg.mcpServers.biomate.command).toBe('npx');
+        (0, vitest_1.expect)(cfg.mcpServers.biomate.env.BIOMATE_REFRESH_TOKEN).toBe('mock_refresh_token');
+    });
+    (0, vitest_1.it)('§3.2.2 claude-code: preserves existing keys in ~/.claude.json', async () => {
+        await fs_1.promises.writeFile(path.join(tmpHome, '.claude.json'), JSON.stringify({ theme: 'dark', mcpServers: { other: { command: 'foo' } } }));
+        const surface = withPort(surfaces_js_1.SURFACES['claude-code']);
+        installOpenStub(mock.url, surface.callbackPort, {});
+        const tokens = await (0, oauth_js_1.runPKCEFlow)(surface, mock.url);
+        await surface.install(tokens.access_token, tokens.refresh_token);
+        const cfg = JSON.parse(await fs_1.promises.readFile(path.join(tmpHome, '.claude.json'), 'utf8'));
+        (0, vitest_1.expect)(cfg.theme).toBe('dark');
+        (0, vitest_1.expect)(cfg.mcpServers.other.command).toBe('foo');
+        (0, vitest_1.expect)(cfg.mcpServers.biomate.command).toBe('npx');
+    });
+    (0, vitest_1.it)('§3.2.3 claude-code: re-install is idempotent (no duplicate biomate entry)', async () => {
+        const surface1 = withPort(surfaces_js_1.SURFACES['claude-code']);
+        installOpenStub(mock.url, surface1.callbackPort, {});
+        let tokens = await (0, oauth_js_1.runPKCEFlow)(surface1, mock.url);
+        await surface1.install(tokens.access_token, tokens.refresh_token);
+        __openHandler = null;
+        const surface2 = withPort(surfaces_js_1.SURFACES['claude-code']); // fresh port
+        installOpenStub(mock.url, surface2.callbackPort, {});
+        tokens = await (0, oauth_js_1.runPKCEFlow)(surface2, mock.url);
+        await surface2.install(tokens.access_token, tokens.refresh_token);
+        const cfg = JSON.parse(await fs_1.promises.readFile(path.join(tmpHome, '.claude.json'), 'utf8'));
+        // Only one `biomate` key — JSON objects can't have duplicates anyway, but
+        // we assert structure is unchanged after second install.
+        (0, vitest_1.expect)(Object.keys(cfg.mcpServers)).toEqual(['biomate']);
+    });
+    (0, vitest_1.it)('§3.2.4 cursor: writes ~/.cursor/mcp.json', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['cursor']);
+        installOpenStub(mock.url, surface.callbackPort, {});
+        const tokens = await (0, oauth_js_1.runPKCEFlow)(surface, mock.url);
+        await surface.install(tokens.access_token, tokens.refresh_token);
+        const cfg = JSON.parse(await fs_1.promises.readFile(path.join(tmpHome, '.cursor', 'mcp.json'), 'utf8'));
+        (0, vitest_1.expect)(cfg.mcpServers.biomate).toBeDefined();
+    });
+    (0, vitest_1.it)('§3.2.5 codex: writes [mcp_servers.biomate] to ~/.codex/config.toml', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['codex']);
+        installOpenStub(mock.url, surface.callbackPort, {});
+        const tokens = await (0, oauth_js_1.runPKCEFlow)(surface, mock.url);
+        await surface.install(tokens.access_token, tokens.refresh_token);
+        const cfg = await fs_1.promises.readFile(path.join(tmpHome, '.codex', 'config.toml'), 'utf8');
+        (0, vitest_1.expect)(cfg).toContain('[mcp_servers.biomate]');
+        (0, vitest_1.expect)(cfg).toContain('mock_refresh_token');
+    });
+    (0, vitest_1.it)('§3.2.6 chatgpt: prints instructions, writes no file', async () => {
+        const surface = surfaces_js_1.SURFACES['chatgpt'];
+        const logSpy = vitest_1.vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        const result = await surface.install('access', 'refresh');
+        (0, vitest_1.expect)(result).toMatch(/ChatGPT/);
+        // No .chatgpt-style files in $HOME.
+        const entries = await fs_1.promises.readdir(tmpHome);
+        (0, vitest_1.expect)(entries).toEqual([]);
+        logSpy.mockRestore();
+    });
+    (0, vitest_1.it)('§3.2.7 open-claw: prints WeChat instructions, writes no file', async () => {
+        const surface = surfaces_js_1.SURFACES['open-claw'];
+        const logSpy = vitest_1.vi.spyOn(console, 'log').mockImplementation(() => undefined);
+        const result = await surface.install('access', 'refresh');
+        (0, vitest_1.expect)(result).toBe('(linked)');
+        const entries = await fs_1.promises.readdir(tmpHome);
+        (0, vitest_1.expect)(entries).toEqual([]);
+        logSpy.mockRestore();
+    });
+    // --- §3.2.9–§3.2.12 — failure modes ---
+    (0, vitest_1.it)('§3.2.10 OAuth callback error=access_denied surfaces cleanly', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['cursor']);
+        installOpenStub(mock.url, surface.callbackPort, { error: 'access_denied' });
+        await (0, vitest_1.expect)((0, oauth_js_1.runPKCEFlow)(surface, mock.url)).rejects.toThrow(/access_denied/);
+    });
+    (0, vitest_1.it)('§3.2.11 state mismatch on callback rejected', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['cursor']);
+        installOpenStub(mock.url, surface.callbackPort, { stateOverride: 'wrong-state' });
+        await (0, vitest_1.expect)((0, oauth_js_1.runPKCEFlow)(surface, mock.url)).rejects.toThrow(/invalid callback/);
+    });
+    (0, vitest_1.it)('§3.2.12 token exchange 400 surfaces the server reply', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['cursor']);
+        mock.behavior.tokenStatus = 400;
+        installOpenStub(mock.url, surface.callbackPort, {});
+        await (0, vitest_1.expect)((0, oauth_js_1.runPKCEFlow)(surface, mock.url)).rejects.toThrow(/token exchange failed: 400/);
+    });
+    // --- §3.2.8 — unknown surface (CLI-level; verified via lookup) ---
+    (0, vitest_1.it)('§3.2.8 unknown surface id returns undefined from SURFACES map', () => {
+        (0, vitest_1.expect)(surfaces_js_1.SURFACES['not-a-surface']).toBeUndefined();
+    });
+    // --- bonus: PKCE verifier is forwarded to token endpoint ---
+    (0, vitest_1.it)('bonus: code_verifier is presented to /oauth/token', async () => {
+        const surface = withPort(surfaces_js_1.SURFACES['cursor']);
+        installOpenStub(mock.url, surface.callbackPort, {});
+        await (0, oauth_js_1.runPKCEFlow)(surface, mock.url);
+        const v = mock.lastVerifier();
+        (0, vitest_1.expect)(v).not.toBeNull();
+        (0, vitest_1.expect)(v.length).toBeGreaterThanOrEqual(43);
+    });
+});

package/dist/__tests__/pkce.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/pkce.test.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const crypto_1 = require("crypto");
+const pkce_js_1 = require("../pkce.js");
+(0, vitest_1.describe)('PKCE', () => {
+    (0, vitest_1.it)('verifier length is in [43, 128]', () => {
+        for (let i = 0; i < 20; i++) {
+            const p = (0, pkce_js_1.generatePKCE)();
+            (0, vitest_1.expect)(p.verifier.length).toBeGreaterThanOrEqual(43);
+            (0, vitest_1.expect)(p.verifier.length).toBeLessThanOrEqual(128);
+        }
+    });
+    (0, vitest_1.it)('challenge equals base64url(sha256(verifier))', () => {
+        const p = (0, pkce_js_1.generatePKCE)();
+        const computed = (0, crypto_1.createHash)('sha256').update(p.verifier).digest('base64')
+            .replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+        (0, vitest_1.expect)(p.challenge).toBe(computed);
+    });
+    (0, vitest_1.it)('uses S256 method', () => {
+        (0, vitest_1.expect)((0, pkce_js_1.generatePKCE)().method).toBe('S256');
+    });
+    (0, vitest_1.it)('verifier and challenge are URL-safe (no +,/,=)', () => {
+        const p = (0, pkce_js_1.generatePKCE)();
+        (0, vitest_1.expect)(p.verifier).not.toMatch(/[+/=]/);
+        (0, vitest_1.expect)(p.challenge).not.toMatch(/[+/=]/);
+    });
+});

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const oauth_js_1 = require("./oauth.js");
+const surfaces_js_1 = require("./surfaces.js");
+const AUTH_BASE = process.env.BIOMATE_AUTH_BASE ?? 'https://api.biomate.ai';
+const USAGE = `\nUsage:  npx @biomate/connect <surface> [--auth-base URL]\n\nSurfaces:\n  claude-code      Anthropic Claude Code (CLI)\n  claude-desktop   Anthropic Claude Desktop\n  cursor           Cursor IDE\n  codex            OpenAI Codex CLI\n  chatgpt          ChatGPT (Custom GPT Actions)\n  open-claw        WeChat / Open Claw\n\nExamples:\n  npx @biomate/connect claude-code\n  npx @biomate/connect cursor\n\nEnvironment:\n  BIOMATE_AUTH_BASE   Auth server URL (default ${AUTH_BASE})\n  BIOMATE_API_BASE    API base URL for installed configs\n`;
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        console.log(USAGE);
+        return 0;
+    }
+    const id = args[0];
+    const surface = surfaces_js_1.SURFACES[id];
+    if (!surface) {
+        console.error(`Unknown surface: ${id}\n${USAGE}`);
+        return 1;
+    }
+    try {
+        const tokens = await (0, oauth_js_1.runPKCEFlow)(surface, AUTH_BASE);
+        const where = await surface.install(tokens.access_token, tokens.refresh_token);
+        // Stash the refresh token in the OS keychain too (best-effort).
+        try {
+            const keytar = await Promise.resolve().then(() => __importStar(require('keytar')));
+            await keytar.default.setPassword('biomate', surface.id, tokens.refresh_token);
+        }
+        catch {
+            /* keychain optional */
+        }
+        console.log(`\n✓ ${surface.label} connected.`);
+        if (where && !where.startsWith('(')) {
+            console.log(`  Config written: ${where}`);
+        }
+        console.log(`  Scopes granted: ${tokens.scope}`);
+        if (id !== 'chatgpt' && id !== 'open-claw') {
+            console.log(`\nRestart ${surface.label} to pick up the new MCP server.`);
+        }
+        return 0;
+    }
+    catch (err) {
+        console.error(`\n✗ Connect failed: ${err.message ?? err}`);
+        return 1;
+    }
+}
+main().then((c) => process.exit(c));

package/dist/configWriters.d.ts

@@ -0,0 +1,2 @@
+export declare function upsertJSON(filePath: string, mutate: (obj: any) => any): Promise<void>;
+export declare function upsertTOML(filePath: string, append: string): Promise<void>;

package/dist/configWriters.js

@@ -0,0 +1,74 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertJSON = upsertJSON;
+exports.upsertTOML = upsertTOML;
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+async function upsertJSON(filePath, mutate) {
+    await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+    let existing = {};
+    try {
+        const raw = await fs_1.promises.readFile(filePath, 'utf8');
+        existing = JSON.parse(raw);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const next = mutate(existing) ?? existing;
+    await atomicWrite(filePath, JSON.stringify(next, null, 2));
+}
+async function upsertTOML(filePath, append) {
+    await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+    let existing = '';
+    try {
+        existing = await fs_1.promises.readFile(filePath, 'utf8');
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    if (existing.includes('[mcp_servers.biomate]')) {
+        // Naive replacement: drop the existing block and re-append.
+        existing = existing.replace(/\n\[mcp_servers\.biomate\][\s\S]*?(?=\n\[|$)/g, '');
+    }
+    await atomicWrite(filePath, existing + append);
+}
+async function atomicWrite(filePath, contents) {
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    await fs_1.promises.writeFile(tmp, contents, 'utf8');
+    await fs_1.promises.rename(tmp, filePath);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { generatePKCE } from './pkce.js';
+export { runPKCEFlow } from './oauth.js';
+export { SURFACES, SurfaceConfig, SurfaceId } from './surfaces.js';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SURFACES = exports.runPKCEFlow = exports.generatePKCE = void 0;
+var pkce_js_1 = require("./pkce.js");
+Object.defineProperty(exports, "generatePKCE", { enumerable: true, get: function () { return pkce_js_1.generatePKCE; } });
+var oauth_js_1 = require("./oauth.js");
+Object.defineProperty(exports, "runPKCEFlow", { enumerable: true, get: function () { return oauth_js_1.runPKCEFlow; } });
+var surfaces_js_1 = require("./surfaces.js");
+Object.defineProperty(exports, "SURFACES", { enumerable: true, get: function () { return surfaces_js_1.SURFACES; } });

package/dist/oauth.d.ts

@@ -0,0 +1,8 @@
+import { SurfaceConfig } from './surfaces.js';
+export interface TokenSet {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope: string;
+}
+export declare function runPKCEFlow(surface: SurfaceConfig, authBaseUrl: string): Promise<TokenSet>;

package/dist/oauth.js

@@ -0,0 +1,97 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPKCEFlow = runPKCEFlow;
+const http_1 = require("http");
+const url_1 = require("url");
+const open_1 = __importDefault(require("open"));
+const pkce_js_1 = require("./pkce.js");
+async function runPKCEFlow(surface, authBaseUrl) {
+    const { verifier, challenge } = (0, pkce_js_1.generatePKCE)();
+    const port = surface.callbackPort;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const state = Math.random().toString(36).slice(2);
+    const codePromise = catchCallback(port, state);
+    // Mark the rejection as handled — the awaiter below will still receive it.
+    // Without this, Node's unhandled-rejection detector fires when the callback
+    // server rejects before `await codePromise` has attached a handler.
+    codePromise.catch(() => undefined);
+    const authUrl = new url_1.URL(`${authBaseUrl}/oauth/authorize`);
+    authUrl.searchParams.set('response_type', 'code');
+    authUrl.searchParams.set('client_id', surface.clientId);
+    authUrl.searchParams.set('redirect_uri', redirectUri);
+    authUrl.searchParams.set('code_challenge', challenge);
+    authUrl.searchParams.set('code_challenge_method', 'S256');
+    authUrl.searchParams.set('scope', surface.scopes.join(' '));
+    authUrl.searchParams.set('state', state);
+    console.log(`\nOpening browser to authorize ${surface.label}…`);
+    console.log(`If it doesn't open, visit:\n  ${authUrl.toString()}\n`);
+    await (0, open_1.default)(authUrl.toString());
+    const code = await codePromise;
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code,
+        redirect_uri: redirectUri,
+        client_id: surface.clientId,
+        code_verifier: verifier,
+    });
+    const resp = await fetch(`${authBaseUrl}/oauth/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body,
+    });
+    if (!resp.ok) {
+        throw new Error(`token exchange failed: ${resp.status} ${await resp.text()}`);
+    }
+    return (await resp.json());
+}
+function catchCallback(port, expectedState) {
+    return new Promise((resolve, reject) => {
+        const server = (0, http_1.createServer)((req, res) => {
+            try {
+                const url = new url_1.URL(req.url ?? '/', `http://127.0.0.1:${port}`);
+                if (url.pathname !== '/callback') {
+                    res.writeHead(404);
+                    res.end();
+                    return;
+                }
+                const code = url.searchParams.get('code');
+                const state = url.searchParams.get('state');
+                const error = url.searchParams.get('error');
+                res.writeHead(200, { 'content-type': 'text/html' });
+                if (error) {
+                    res.end(htmlResult(`Authorization failed: ${error}`, false));
+                    server.close();
+                    reject(new Error(error));
+                    return;
+                }
+                if (!code || state !== expectedState) {
+                    res.end(htmlResult('Invalid callback (missing code or state mismatch).', false));
+                    server.close();
+                    reject(new Error('invalid callback'));
+                    return;
+                }
+                res.end(htmlResult('Connected! You can close this tab.', true));
+                server.close();
+                resolve(code);
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+        server.on('error', reject);
+        server.listen(port, '127.0.0.1');
+        setTimeout(() => {
+            server.close();
+            reject(new Error('OAuth callback timed out after 3 minutes'));
+        }, 3 * 60 * 1000);
+    });
+}
+function htmlResult(message, ok) {
+    const color = ok ? '#0a7' : '#c33';
+    return `<!doctype html><html><body style="font:14px/1.5 -apple-system,sans-serif;text-align:center;margin-top:80px">
+<h1 style="color:${color}">${message}</h1>
+<p style="color:#666">BioMate connector installer</p></body></html>`;
+}

package/dist/pkce.d.ts

@@ -0,0 +1,6 @@
+export interface PKCEPair {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+export declare function generatePKCE(): PKCEPair;

package/dist/pkce.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePKCE = generatePKCE;
+const crypto_1 = require("crypto");
+function generatePKCE() {
+    const verifier = base64url((0, crypto_1.randomBytes)(48));
+    const challenge = base64url((0, crypto_1.createHash)('sha256').update(verifier).digest());
+    return { verifier, challenge, method: 'S256' };
+}
+function base64url(buf) {
+    return buf
+        .toString('base64')
+        .replace(/=/g, '')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_');
+}

package/dist/surfaces.d.ts

@@ -0,0 +1,13 @@
+export type SurfaceId = 'claude-code' | 'claude-desktop' | 'cursor' | 'codex' | 'chatgpt' | 'open-claw';
+export interface SurfaceConfig {
+    id: SurfaceId;
+    label: string;
+    clientId: string;
+    callbackPort: number;
+    scopes: string[];
+    /** Path of the host's MCP config file. */
+    configPath: () => string;
+    /** Path-agnostic config writer. Returns a description of what changed. */
+    install: (token: string, refreshToken: string) => Promise<string>;
+}
+export declare const SURFACES: Record<SurfaceId, SurfaceConfig>;

package/dist/surfaces.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SURFACES = void 0;
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const DEFAULT_SCOPES = [
+    'runs:read',
+    'runs:write',
+    'workflows:search',
+    'memory:read',
+    'memory:write',
+    'files:upload',
+    'reports:export',
+    'billing:read',
+];
+function home() {
+    return os.homedir();
+}
+function platformConfigDir() {
+    if (process.platform === 'darwin')
+        return path.join(home(), 'Library', 'Application Support');
+    if (process.platform === 'win32')
+        return process.env.APPDATA ?? home();
+    return path.join(home(), '.config');
+}
+function mcpServerEntry(refreshToken) {
+    const apiBase = process.env.BIOMATE_API_BASE ?? 'https://api.biomate.ai';
+    return {
+        command: 'npx',
+        args: ['-y', '@biomate/mcp-server'],
+        env: {
+            BIOMATE_API_BASE: apiBase,
+            BIOMATE_REFRESH_TOKEN: refreshToken,
+        },
+    };
+}
+const configWriters_js_1 = require("./configWriters.js");
+exports.SURFACES = {
+    'claude-code': {
+        id: 'claude-code',
+        label: 'Claude Code',
+        clientId: 'biomate-claude-code',
+        callbackPort: 53682,
+        scopes: DEFAULT_SCOPES,
+        configPath: () => path.join(home(), '.claude.json'),
+        install: async (_t, refresh) => {
+            const p = path.join(home(), '.claude.json');
+            await (0, configWriters_js_1.upsertJSON)(p, (cfg) => {
+                cfg.mcpServers ??= {};
+                cfg.mcpServers.biomate = mcpServerEntry(refresh);
+                return cfg;
+            });
+            return p;
+        },
+    },
+    'claude-desktop': {
+        id: 'claude-desktop',
+        label: 'Claude Desktop',
+        clientId: 'biomate-claude-desktop',
+        callbackPort: 53683,
+        scopes: DEFAULT_SCOPES,
+        configPath: () => path.join(platformConfigDir(), 'Claude', 'claude_desktop_config.json'),
+        install: async (_t, refresh) => {
+            const p = path.join(platformConfigDir(), 'Claude', 'claude_desktop_config.json');
+            await (0, configWriters_js_1.upsertJSON)(p, (cfg) => {
+                cfg.mcpServers ??= {};
+                cfg.mcpServers.biomate = mcpServerEntry(refresh);
+                return cfg;
+            });
+            return p;
+        },
+    },
+    cursor: {
+        id: 'cursor',
+        label: 'Cursor',
+        clientId: 'biomate-cursor',
+        callbackPort: 53684,
+        scopes: DEFAULT_SCOPES,
+        configPath: () => path.join(home(), '.cursor', 'mcp.json'),
+        install: async (_t, refresh) => {
+            const p = path.join(home(), '.cursor', 'mcp.json');
+            await (0, configWriters_js_1.upsertJSON)(p, (cfg) => {
+                cfg.mcpServers ??= {};
+                cfg.mcpServers.biomate = mcpServerEntry(refresh);
+                return cfg;
+            });
+            return p;
+        },
+    },
+    codex: {
+        id: 'codex',
+        label: 'Codex CLI',
+        clientId: 'biomate-codex',
+        callbackPort: 53685,
+        scopes: DEFAULT_SCOPES,
+        configPath: () => path.join(home(), '.codex', 'config.toml'),
+        install: async (_t, refresh) => {
+            const p = path.join(home(), '.codex', 'config.toml');
+            const apiBase = process.env.BIOMATE_API_BASE ?? 'https://api.biomate.ai';
+            await (0, configWriters_js_1.upsertTOML)(p, `\n[mcp_servers.biomate]\ncommand = "npx"\nargs = ["-y", "@biomate/mcp-server"]\n\n[mcp_servers.biomate.env]\nBIOMATE_API_BASE = "${apiBase}"\nBIOMATE_REFRESH_TOKEN = "${refresh}"\n`);
+            return p;
+        },
+    },
+    chatgpt: {
+        id: 'chatgpt',
+        label: 'ChatGPT',
+        clientId: 'biomate-chatgpt',
+        callbackPort: 53686, // Not actually used — ChatGPT does OAuth in-app.
+        scopes: DEFAULT_SCOPES,
+        configPath: () => '(ChatGPT Actions — configured in chat.openai.com)',
+        install: async () => {
+            console.log(`
+ChatGPT connects to BioMate via Custom GPT Actions, not a local config file.
+Install steps:
+  1. Visit https://chatgpt.com/gpts/editor and create a new GPT.
+  2. Import OpenAPI from: https://api.biomate.ai/connectors/chatgpt/openapi.json
+  3. Enable OAuth in the Actions panel:
+       Authorization URL: https://api.biomate.ai/oauth/authorize
+       Token URL:         https://api.biomate.ai/oauth/token
+       Client ID:         biomate-chatgpt
+       Scope:             ${DEFAULT_SCOPES.join(' ')}
+  4. Save and test with: "Screen aspirin for hERG"
+`);
+            return '(ChatGPT in-app setup)';
+        },
+    },
+    'open-claw': {
+        id: 'open-claw',
+        label: 'Open Claw (WeChat)',
+        clientId: 'biomate-open-claw',
+        callbackPort: 53687,
+        scopes: DEFAULT_SCOPES,
+        configPath: () => '(Open Claw — hosted by BioMate)',
+        install: async (_t, refresh) => {
+            console.log(`
+Open Claw runs as a hosted webhook — there's nothing to install locally.
+We've linked your account; in WeChat search the BioMate Open Claw bot and
+say hi.
+`);
+            return '(linked)';
+        },
+    },
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@biomate/connect",
+  "version": "0.1.0",
+  "description": "One-line installer that connects BioMate to Claude Code, Claude Desktop, Cursor, Codex, and ChatGPT via OAuth 2.1 + PKCE.",
+  "bin": {
+    "biomate-connect": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["biomate", "mcp", "claude", "cursor", "codex", "chatgpt", "bioinformatics"],
+  "author": "BioMate AI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bioMate-AI/biomate-connectors.git",
+    "directory": "installer"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "keytar": "^7.9.0",
+    "open": "^9.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^1.0.0"
+  },
+  "files": ["dist", "README.md"],
+  "publishConfig": {
+    "access": "public"
+  }
+}