@harness-fe/mcp-server 4.0.0-next.1 → 4.0.0-next.3

package/src/cli.ts

@@ -1,338 +0,0 @@
-#!/usr/bin/env node
-/**
- * CLI entry — boots WS bridge + MCP server (stdio or HTTP).
- *
- * Usage:
- *   npx @harness-fe/mcp-server                # 127.0.0.1, stdio MCP
- *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto
- *   npx @harness-fe/mcp-server --host 0.0.0.0 --token auto --mcp-transport http
- *
- * Leader / follower:
- *   - first process bound to the WS port = leader (in-process Bridge)
- *   - subsequent processes (EADDRINUSE) become followers that attach to
- *     the leader via the `mcp.call` control channel using `RemoteBridge`.
- *
- * This lets multiple Claude Code windows share a single dev-bridge daemon
- * (and thus the same browser / vite-plugin connections).
- */
-
-import { randomBytes } from 'node:crypto';
-import {
-    DEFAULT_HOST,
-    DEFAULT_WS_PORT,
-    buildHttpUrl,
-    isLoopbackHost,
-    parseWsUrl,
-} from '@harness-fe/protocol';
-import { defaultDataDir, type IBridge } from './bridge.js';
-import { createDaemon, type DaemonHandle } from './daemon.js';
-import { RemoteBridge } from './remoteBridge.js';
-import { startMcpStdioServer } from './mcp.js';
-
-type McpTransport = 'stdio' | 'http';
-
-interface CliConfig {
-    host: string;
-    port: number;
-    token: string | undefined;
-    mcpTransport: McpTransport;
-    mcpPath: string;
-    publicHost: string | undefined;
-    /** Friendly daemon name; surfaces in banner / dashboard. Cosmetic only. */
-    label: string | undefined;
-    /** Resolved data directory. Defaults to defaultDataDir(port). */
-    dataDir: string;
-    /** Env-var name that gates experimental tools. Undefined = fully on (no gate). */
-    experimentalEnvVar: string | undefined;
-}
-
-function printHelpAndExit(): never {
-    const help = `harness-fe — frontend harness MCP daemon
-
-Usage:
-  harness-fe [options]
-
-Options:
-  --host <addr>          Bind address. Default 127.0.0.1.
-                         Use 0.0.0.0 to accept LAN connections (requires --token).
-  --port <number>        TCP port. Default ${DEFAULT_WS_PORT}.
-  --token <value|auto>   Token required for HTTP/WS auth. Pass "auto" to generate one.
-                         Required when --host is not loopback.
-  --mcp-transport <kind> stdio (default) or http. http mounts /mcp on the bridge.
-  --mcp-path <path>      URL path for the MCP HTTP endpoint. Default /mcp.
-  --public-host <addr>   Override the host printed in outbound URLs. Useful when
-                         binding 0.0.0.0 and the auto-detected LAN IP is wrong.
-  --experimental-env-var <name>
-                         Restrict experimental (in-testing) tools to machines
-                         where <name> is set to a non-empty value. Omit this and
-                         experimental tools are fully on (the default).
-  -h, --help             Show this help.
-
-Environment:
-  HARNESS_FE_HOST                Same as --host
-  HARNESS_FE_TOKEN               Same as --token (use "auto" to generate)
-  HARNESS_FE_MCP_TRANSPORT       Same as --mcp-transport
-  HARNESS_FE_MCP_PATH            Same as --mcp-path
-  HARNESS_FE_EXPERIMENTAL_ENV_VAR  Same as --experimental-env-var
-  HARNESS_FE_URL                 Full ws:// URL (legacy; --host/--port override it)
-`;
-    process.stderr.write(help);
-    process.exit(0);
-}
-
-function parseArgs(argv: string[]): CliConfig {
-    const args = argv.slice(2);
-
-    let host: string | undefined;
-    let port: number | undefined;
-    let token: string | undefined;
-    let mcpTransport: McpTransport | undefined;
-    let mcpPath: string | undefined;
-    let publicHost: string | undefined;
-    let experimentalEnvVar: string | undefined;
-
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i];
-        const next = () => {
-            const v = args[++i];
-            if (v == null) {
-                process.stderr.write(`harness-fe: missing value for ${a}\n`);
-                process.exit(2);
-            }
-            return v;
-        };
-        switch (a) {
-            case '-h':
-            case '--help':
-                printHelpAndExit();
-                break;
-            case '--host':
-                host = next();
-                break;
-            case '--port':
-                port = Number(next());
-                if (!Number.isFinite(port) || port <= 0) {
-                    process.stderr.write(`harness-fe: invalid --port\n`);
-                    process.exit(2);
-                }
-                break;
-            case '--token':
-                token = next();
-                break;
-            case '--mcp-transport': {
-                const v = next();
-                if (v !== 'stdio' && v !== 'http') {
-                    process.stderr.write(`harness-fe: invalid --mcp-transport (stdio|http)\n`);
-                    process.exit(2);
-                }
-                mcpTransport = v;
-                break;
-            }
-            case '--mcp-path':
-                mcpPath = next();
-                break;
-            case '--public-host':
-                publicHost = next();
-                break;
-            case '--experimental-env-var':
-                experimentalEnvVar = next();
-                break;
-            default:
-                process.stderr.write(`harness-fe: unknown argument ${a}\n`);
-                process.exit(2);
-        }
-    }
-
-    // Apply env fallbacks, then URL fallback for host/port.
-    const envUrl = process.env.HARNESS_FE_URL;
-    let envHost: string | undefined;
-    let envPort: number | undefined;
-    if (envUrl) {
-        try {
-            const parsed = parseWsUrl(envUrl);
-            envHost = parsed.host;
-            envPort = parsed.port;
-        } catch {
-            // ignore — fall back to defaults below
-        }
-    }
-
-    const finalHost = host ?? process.env.HARNESS_FE_HOST ?? envHost ?? DEFAULT_HOST;
-    const finalPort = port ?? envPort ?? DEFAULT_WS_PORT;
-
-    let finalToken = token ?? process.env.HARNESS_FE_TOKEN;
-    if (finalToken === 'auto') {
-        finalToken = randomBytes(24).toString('base64url');
-    }
-    if (finalToken === '') finalToken = undefined;
-
-    const finalTransport: McpTransport =
-        (mcpTransport ?? (process.env.HARNESS_FE_MCP_TRANSPORT as McpTransport | undefined)) ??
-        'stdio';
-    if (finalTransport !== 'stdio' && finalTransport !== 'http') {
-        process.stderr.write(`harness-fe: invalid mcp transport "${finalTransport}"\n`);
-        process.exit(2);
-    }
-    const finalMcpPath = mcpPath ?? process.env.HARNESS_FE_MCP_PATH ?? '/mcp';
-
-    // Data dir defaults to port-keyed path. Explicit env override wins.
-    const finalDataDir = process.env.HARNESS_FE_DATA_DIR ?? defaultDataDir(finalPort);
-
-    const finalLabel = process.env.HARNESS_FE_LABEL || undefined;
-
-    // Omitted → undefined → experimental tools fully on (no gate). Supply a
-    // name only to restrict them to machines where that var is set.
-    const finalExperimentalEnvVar =
-        experimentalEnvVar || process.env.HARNESS_FE_EXPERIMENTAL_ENV_VAR || undefined;
-
-    return {
-        host: finalHost,
-        port: finalPort,
-        token: finalToken,
-        mcpTransport: finalTransport,
-        mcpPath: finalMcpPath,
-        publicHost,
-        label: finalLabel,
-        dataDir: finalDataDir,
-        experimentalEnvVar: finalExperimentalEnvVar,
-    };
-}
-
-function validate(_cfg: CliConfig): void {
-    // Token requirement is left entirely to the operator. We don't refuse
-    // a non-loopback bind without a token — that's their call, not ours.
-    // Warnings are emitted from the banner so the operator sees them; CI /
-    // automation that pipes stderr can suppress as needed.
-}
-
-function printBanner(cfg: CliConfig, role: 'leader' | 'follower', viewerUrl: string | undefined): void {
-    const lines: string[] = [];
-    const labelSuffix = cfg.label ? `  (${cfg.label})` : '';
-    lines.push(`[harness-fe] ${role}: WS bridge listening on ws://${cfg.host}:${cfg.port}${labelSuffix}`);
-    if (role === 'leader') {
-        // Surface the data dir so the user can see exactly where this
-        // daemon's sessions / recordings / projects are landing.
-        lines.push(`[harness-fe] data:   ${cfg.dataDir}`);
-    }
-    const isLan = !isLoopbackHost(cfg.host);
-    if (isLan) {
-        lines.push(`[harness-fe] WARNING: bound to non-loopback host ${cfg.host}.`);
-        if (cfg.token) {
-            lines.push(`[harness-fe]   anyone reaching this host:port with the token can read console / network / recordings.`);
-        } else {
-            lines.push(`[harness-fe]   no token set — anyone on this network can read console / network / recordings.`);
-            lines.push(`[harness-fe]   add --token auto (or HARNESS_FE_TOKEN=…) to enable auth.`);
-        }
-    }
-    // Always print the dashboard URL. The token (when present) is folded
-    // into the query so the first hit hands it off to a cookie; without a
-    // token, auth is disabled and the URL works on its own.
-    const host = cfg.publicHost ?? viewerHost(viewerUrl) ?? cfg.host;
-    const dashboard = buildHttpUrl({ host, port: cfg.port, token: cfg.token });
-    lines.push(`[harness-fe] dashboard: ${dashboard}`);
-    if (cfg.mcpTransport === 'http') {
-        const mcp = buildHttpUrl({ host, port: cfg.port, token: cfg.token, path: cfg.mcpPath });
-        lines.push(`[harness-fe] mcp http:  ${mcp}`);
-        if (cfg.token) {
-            const mcpNoTok = buildHttpUrl({ host, port: cfg.port, path: cfg.mcpPath });
-            lines.push(
-                `[harness-fe]   agent config: { "url": "${mcpNoTok}", "headers": { "Authorization": "Bearer ${cfg.token}" } }`,
-            );
-        } else {
-            lines.push(`[harness-fe]   agent config: { "url": "${mcp}" }   (no auth — token unset)`);
-        }
-    }
-    if (cfg.token) {
-        lines.push(`[harness-fe] token:     ${cfg.token}`);
-    }
-    process.stderr.write(lines.join('\n') + '\n');
-}
-
-function viewerHost(viewerUrl: string | undefined): string | undefined {
-    if (!viewerUrl) return undefined;
-    try {
-        return new URL(viewerUrl).hostname;
-    } catch {
-        return undefined;
-    }
-}
-
-async function main() {
-    const cfg = parseArgs(process.argv);
-    validate(cfg);
-
-    const { active, shutdown, role } = await startBridgeOrAttach(cfg);
-    printBanner(cfg, role, active.getViewerBaseUrl());
-
-    if (cfg.mcpTransport === 'stdio') {
-        await startMcpStdioServer(active, { experimentalEnvVar: cfg.experimentalEnvVar });
-        process.stderr.write('[harness-fe] MCP stdio server connected\n');
-    } else {
-        // HTTP transport: the leader's createDaemon() call already mounted
-        // /mcp via mcpHttp:true. Followers fall through here with no leader
-        // attached, so HTTP mode is unsupported for them.
-        if (role === 'follower') {
-            process.stderr.write(
-                '[harness-fe] --mcp-transport=http is only supported on the leader. ' +
-                    'Another daemon already holds the port; stop it first.\n',
-            );
-            await shutdown();
-            process.exit(2);
-        }
-        process.stderr.write(`[harness-fe] MCP http server mounted at ${cfg.mcpPath}\n`);
-    }
-
-    const onSignal = async () => {
-        process.stderr.write('[harness-fe] shutting down\n');
-        await shutdown();
-        process.exit(0);
-    };
-    process.on('SIGINT', onSignal);
-    process.on('SIGTERM', onSignal);
-}
-
-async function startBridgeOrAttach(
-    cfg: CliConfig,
-): Promise<{ active: IBridge; shutdown: () => Promise<void>; role: 'leader' | 'follower' }> {
-    // Leader path: use createDaemon so there's exactly one boot path between
-    // the CLI and any host application that embeds the daemon. The factory
-    // mounts /mcp itself when mcpHttp:true, so we don't need to call
-    // startMcpHttpServer here.
-    const daemon: DaemonHandle = createDaemon({
-        port: cfg.port,
-        host: cfg.host,
-        dataDir: cfg.dataDir,
-        label: cfg.label,
-        token: cfg.token,
-        publicHost: cfg.publicHost,
-        mcpHttp: cfg.mcpTransport === 'http',
-        mcpPath: cfg.mcpPath,
-        experimentalEnvVar: cfg.experimentalEnvVar,
-    });
-    try {
-        await daemon.start();
-        return {
-            active: daemon.bridge,
-            shutdown: () => daemon.stop(),
-            role: 'leader',
-        };
-    } catch (err) {
-        if ((err as NodeJS.ErrnoException)?.code !== 'EADDRINUSE') throw err;
-        // Factory's bridge.start failed on EADDRINUSE; the factory itself
-        // didn't mount anything else, so there's nothing further to clean up.
-    }
-
-    // Port already taken — attach as follower.
-    const remote = new RemoteBridge({ port: cfg.port, host: cfg.host, token: cfg.token });
-    await remote.connect();
-    return {
-        active: remote,
-        shutdown: () => remote.stop(),
-        role: 'follower',
-    };
-}
-
-main().catch((err) => {
-    process.stderr.write(`[harness-fe] fatal: ${err?.stack ?? err}\n`);
-    process.exit(1);
-});

package/src/dashboardApi.test.ts

@@ -1,235 +0,0 @@
-/**
- * Tests for the JSON API surface consumed by @harness-fe/dashboard-ui.
- *
- * Mirrors the seed setup used by `dashboard.test.ts` so we have parity:
- * anything the HTML dashboard could show should also be reachable via JSON
- * once we ship the SPA in PR C.
- */
-
-import { afterEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { Bridge } from './bridge.js';
-import { JsonlStore } from './store/index.js';
-
-const tempDirs: string[] = [];
-function mkTmp(): string {
-    const dir = mkdtempSync(join(tmpdir(), 'harness-dashboard-api-test-'));
-    tempDirs.push(dir);
-    return dir;
-}
-
-afterEach(async () => {
-    while (tempDirs.length) {
-        const d = tempDirs.pop()!;
-        try { rmSync(d, { recursive: true, force: true }); } catch { /* ignore */ }
-    }
-});
-
-async function bootBridge() {
-    const dir = mkTmp();
-    const store = new JsonlStore(dir);
-    const bridge = new Bridge({ port: 0, host: '127.0.0.1', store, taskStore: null, memoryStore: null });
-    await bridge.start();
-    const port = bridge.getBoundPort();
-    if (!port) throw new Error('no port');
-    return { bridge, store, port };
-}
-
-function seed(store: JsonlStore, projectId: string): string {
-    const { randomUUID } = require('node:crypto') as typeof import('node:crypto');
-    const sessionId = randomUUID();
-    store.upsertProject(projectId, { displayName: projectId });
-    store.upsertTab('tab-1', { connectedAt: Date.now(), userAgent: 'test-agent' });
-    store.upsertSession(sessionId, {
-        tabId: 'tab-1',
-        startedAt: Date.now(),
-        url: 'http://localhost:5173/',
-        title: 'Demo',
-        participants: [{ projectId, joinedAt: Date.now() }],
-    });
-    store.appendEvent(sessionId, { ts: 1000, t: 'log', d: { args: ['hello'] } });
-    store.appendEvent(sessionId, { ts: 1100, t: 'err', d: { message: 'boom' } });
-    store.appendRecording(sessionId, {
-        chunkId: 'rrc_a', startTs: 1000, endTs: 2000, eventCount: 3,
-        events: [
-            { type: 4, data: {}, timestamp: 1000 },
-            { type: 2, data: {}, timestamp: 1100 },
-            { type: 3, data: {}, timestamp: 2000 },
-        ],
-    });
-    return sessionId;
-}
-
-describe('Dashboard JSON API', () => {
-    it('GET /api/projects returns project list with recent sessions inline', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            const sessionId = seed(store, 'my-app');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/api/projects`);
-            expect(resp.status).toBe(200);
-            expect(resp.headers.get('content-type')).toMatch(/application\/json/);
-            const body = await resp.json() as { projects: Array<{ project: { id: string }; recentSessions: Array<{ id: string }> }> };
-            expect(body.projects).toHaveLength(1);
-            expect(body.projects[0].project.id).toBe('my-app');
-            expect(body.projects[0].recentSessions.map((s) => s.id)).toContain(sessionId);
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('GET /api/projects on empty store returns an empty list (not 500)', async () => {
-        const { bridge, port } = await bootBridge();
-        try {
-            const resp = await fetch(`http://127.0.0.1:${port}/api/projects`);
-            expect(resp.status).toBe(200);
-            const body = await resp.json() as { projects: unknown[] };
-            expect(body.projects).toEqual([]);
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('GET /api/sessions filters by projectId', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            seed(store, 'project-a');
-            seed(store, 'project-b');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/api/sessions?projectId=project-a`);
-            expect(resp.status).toBe(200);
-            const body = await resp.json() as { sessions: Array<{ participants: Array<{ projectId: string }> }> };
-            expect(body.sessions.length).toBeGreaterThan(0);
-            for (const s of body.sessions) {
-                expect(s.participants[0].projectId).toBe('project-a');
-            }
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('GET /api/sessions/:id returns session + summary + chunks + timeline + exports', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            const sessionId = seed(store, 'my-app');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/api/sessions/${sessionId}`);
-            expect(resp.status).toBe(200);
-            const body = await resp.json() as {
-                session: { id: string };
-                summary: { tabs: string[] };
-                chunks: Array<{ chunkId: string; tabId: string; eventCount: number }>;
-                timeline: Array<{ t: string }>;
-                exports: unknown[];
-            };
-            expect(body.session.id).toBe(sessionId);
-            expect(body.summary.tabs).toContain('tab-1');
-            expect(body.chunks).toHaveLength(1);
-            expect(body.chunks[0].chunkId).toBe('rrc_a');
-            expect(body.chunks[0].eventCount).toBe(3);
-            expect(body.timeline.map((e) => e.t)).toContain('log');
-            expect(body.timeline.map((e) => e.t)).toContain('err');
-            expect(body.exports).toEqual([]);
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('GET /api/sessions/:id returns 404 for unknown id', async () => {
-        const { bridge, port } = await bootBridge();
-        try {
-            const resp = await fetch(`http://127.0.0.1:${port}/api/sessions/no-such-session`);
-            expect(resp.status).toBe(404);
-            const body = await resp.json() as { error: string; sessionId: string };
-            expect(body.error).toMatch(/not found/i);
-            expect(body.sessionId).toBe('no-such-session');
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('POST /api/sessions/:id/replay returns exportId + viewerUrl on success', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            const sessionId = seed(store, 'my-app');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/api/sessions/${sessionId}/replay`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body: JSON.stringify({ since: 1000, until: 3000, tabId: 'tab-1' }),
-            });
-            expect(resp.status).toBe(200);
-            const body = await resp.json() as { exportId?: string; viewerUrl?: string; error?: string };
-            expect(body.error).toBeUndefined();
-            expect(body.exportId).toBeTruthy();
-            // viewerUrl is best-effort (depends on bridge.getViewerBaseUrl()); just assert shape.
-            expect(typeof body.exportId === 'string').toBe(true);
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('POST /api/sessions/:id/replay returns 400 with error message for empty window', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            const sessionId = seed(store, 'my-app');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/api/sessions/${sessionId}/replay`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body: JSON.stringify({ since: 999_999_000, until: 999_999_100 }),
-            });
-            expect(resp.status).toBe(400);
-            const body = await resp.json() as { error: string };
-            expect(body.error).toMatch(/no rrweb chunks|empty|window/i);
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('POST /api/sessions/:id/replay rejects malformed JSON with 400', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            const sessionId = seed(store, 'my-app');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/api/sessions/${sessionId}/replay`, {
-                method: 'POST',
-                headers: { 'content-type': 'application/json' },
-                body: 'not json {{{',
-            });
-            expect(resp.status).toBe(400);
-            const body = await resp.json() as { error: string };
-            expect(body.error).toMatch(/invalid JSON/i);
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('non-API root path redirects into the SPA (legacy / no longer serves HTML)', async () => {
-        const { bridge, store, port } = await bootBridge();
-        try {
-            seed(store, 'my-app');
-            await store.flush();
-            const resp = await fetch(`http://127.0.0.1:${port}/?token=abc`, { redirect: 'manual' });
-            expect(resp.status).toBe(302);
-            expect(resp.headers.get('location')).toBe('/dashboard/?token=abc');
-        } finally {
-            await bridge.stop();
-        }
-    });
-
-    it('unknown /api/* paths return 404 JSON (not the HTML 404 page)', async () => {
-        const { bridge, port } = await bootBridge();
-        try {
-            const resp = await fetch(`http://127.0.0.1:${port}/api/bogus/path`);
-            expect(resp.status).toBe(404);
-            expect(resp.headers.get('content-type')).toMatch(/application\/json/);
-            const body = await resp.json() as { error: string };
-            expect(body.error).toBe('not found');
-        } finally {
-            await bridge.stop();
-        }
-    });
-});