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

package/src/replayCreate.ts

@@ -1,194 +0,0 @@
-/**
- * Shared replay-export logic used by both the leader's MCP tool handler and
- * the leader's mcp.call dispatcher (for follower proxy calls).
- *
- * Takes a time window (or a center timestamp), pulls the overlapping rrweb
- * chunks for a single tab, concatenates the events, persists them as an
- * export, and returns the metadata + viewerUrl.
- */
-
-import type { IStore } from './store/index.js';
-
-/** rrweb event types: 2 = FullSnapshot baseline. Replay needs at least one. */
-function isFullSnapshotEvent(ev: unknown): boolean {
-    return (
-        typeof ev === 'object' &&
-        ev !== null &&
-        (ev as { type?: unknown }).type === 2
-    );
-}
-
-export interface ReplayCreateArgs {
-    sessionId: string;
-    tabId?: string;
-    ts?: number;
-    windowMs?: number;
-    since?: number;
-    until?: number;
-    label?: string;
-}
-
-export interface ReplayCreateResult {
-    exportId?: string;
-    viewerUrl?: string;
-    sessionId: string;
-    tabId?: string;
-    since: number;
-    until: number;
-    startTs?: number;
-    endTs?: number;
-    durationMs?: number;
-    eventCount?: number;
-    chunkCount?: number;
-    bytes?: number;
-    createdAt?: number;
-    label?: string;
-    error?: string;
-}
-
-export function createReplayExport(
-    store: IStore,
-    baseUrl: string | undefined,
-    input: ReplayCreateArgs,
-): ReplayCreateResult {
-    const { sessionId, tabId, ts, windowMs, since, until, label } = input;
-
-    const session = store.getSession(sessionId);
-    if (!session) {
-        return { error: 'session not found', sessionId, since: since ?? 0, until: until ?? 0 };
-    }
-
-    let resolvedSince: number;
-    let resolvedUntil: number;
-    if (typeof since === 'number' && typeof until === 'number') {
-        if (until <= since) {
-            return { error: 'until must be greater than since', sessionId, since, until };
-        }
-        resolvedSince = since;
-        resolvedUntil = until;
-    } else if (typeof ts === 'number') {
-        const radius = windowMs ?? 15_000;
-        resolvedSince = ts - radius;
-        resolvedUntil = ts + radius;
-    } else {
-        return {
-            error: 'must provide either ts (with optional windowMs) or both since and until',
-            sessionId,
-            since: 0,
-            until: 0,
-        };
-    }
-
-    const chunks = store.sliceRecordings(sessionId, resolvedSince, resolvedUntil);
-    if (chunks.length === 0) {
-        return {
-            error: 'no rrweb chunks found in window',
-            sessionId,
-            tabId,
-            since: resolvedSince,
-            until: resolvedUntil,
-        };
-    }
-
-    let scopedTabId = tabId;
-    if (!scopedTabId) {
-        const byTab = new Map<string, number>();
-        for (const c of chunks) byTab.set(c.tabId, (byTab.get(c.tabId) ?? 0) + c.eventCount);
-        let best = '';
-        let bestEvents = -1;
-        for (const [t, count] of byTab) {
-            if (count > bestEvents) { best = t; bestEvents = count; }
-        }
-        scopedTabId = best;
-    }
-
-    const tabChunks = chunks.filter((c) => c.tabId === scopedTabId);
-    const events: unknown[] = [];
-    let startTs = Infinity;
-    let endTs = -Infinity;
-    for (const c of tabChunks) {
-        for (const ev of c.events) events.push(ev);
-        if (c.startTs < startTs) startTs = c.startTs;
-        if (c.endTs > endTs) endTs = c.endTs;
-    }
-
-    // rrweb replay requires a baseline pair — type:4 (Meta) + type:2
-    // (FullSnapshot) — before any type:3 (IncrementalSnapshot) is meaningful.
-    // If the window only contains incremental mutations (e.g. user picked a
-    // narrow window long after the page loaded, or the very first chunk was
-    // lost during a daemon restart), look back across earlier chunks for the
-    // most recent baseline and prepend it. Replay will then start from that
-    // earlier DOM state and roll mutations forward into the window.
-    if (!events.some(isFullSnapshotEvent) && resolvedSince > 0) {
-        const priorChunks = store
-            .sliceRecordings(sessionId, 0, resolvedSince - 1)
-            .filter((c) => c.tabId === scopedTabId)
-            .sort((a, b) => a.startTs - b.startTs);
-        // Walk backwards from the chunk closest to window start; the first
-        // chunk that has a FullSnapshot becomes our baseline.
-        for (let i = priorChunks.length - 1; i >= 0; i--) {
-            const baseline = priorChunks[i];
-            if (!baseline) continue;
-            if (baseline.events.some(isFullSnapshotEvent)) {
-                // Prepend baseline events (full chunk — preserves Meta + FS
-                // ordering rrweb emitted them in). startTs widens to baseline.
-                events.unshift(...baseline.events);
-                if (baseline.startTs < startTs) startTs = baseline.startTs;
-                break;
-            }
-        }
-    }
-
-    if (events.length < 2) {
-        return {
-            error: 'window contains fewer than 2 rrweb events — not enough to replay',
-            sessionId,
-            tabId: scopedTabId,
-            since: resolvedSince,
-            until: resolvedUntil,
-            eventCount: events.length,
-        };
-    }
-    if (!events.some(isFullSnapshotEvent)) {
-        return {
-            error:
-                'window contains no rrweb FullSnapshot (type:2) baseline, and no earlier baseline could be found — replay would be blank',
-            sessionId,
-            tabId: scopedTabId,
-            since: resolvedSince,
-            until: resolvedUntil,
-            eventCount: events.length,
-        };
-    }
-
-    const meta = store.writeExport({
-        sessionId,
-        tabId: scopedTabId,
-        since: resolvedSince,
-        until: resolvedUntil,
-        label,
-        events,
-        startTs,
-        endTs,
-        chunkCount: tabChunks.length,
-    });
-
-    const viewerUrl = baseUrl ? `${baseUrl}/replay/${meta.exportId}` : undefined;
-
-    return {
-        exportId: meta.exportId,
-        viewerUrl,
-        sessionId,
-        tabId: scopedTabId,
-        since: resolvedSince,
-        until: resolvedUntil,
-        startTs,
-        endTs,
-        durationMs: endTs - startTs,
-        eventCount: meta.eventCount,
-        chunkCount: meta.chunkCount,
-        bytes: meta.bytes,
-        createdAt: meta.createdAt,
-        label,
-    };
-}

package/src/replayViewer.ts

@@ -1,173 +0,0 @@
-/**
- * Replay viewer — HTTP routes for serving exported rrweb recordings.
- *
- * Routes (all served on the same port as the WS bridge):
- *   GET /replay/:id           HTML viewer page (rrweb-player UI)
- *   GET /replay/:id.json      Raw events array for the player to fetch
- *   GET /replay/static/player.js   Bundled rrweb-player (UMD)
- *   GET /replay/static/player.css  Bundled rrweb-player styles
- *
- * The HTML page loads the static assets relatively and then calls
- * /replay/:id.json to hydrate the player. This keeps the viewer self-contained
- * and offline-capable — no CDN dependencies.
- */
-
-import { readFileSync, existsSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import type { IStore } from './store/index.js';
-
-const require = createRequire(import.meta.url);
-
-/** Locate the bundled rrweb-player dist directory. */
-function resolvePlayerDist(): string {
-    // rrweb-player exposes package.json; use it to find the dist folder.
-    const pkgPath = require.resolve('rrweb-player/package.json');
-    return join(dirname(pkgPath), 'dist');
-}
-
-const PLAYER_DIST = (() => {
-    try { return resolvePlayerDist(); } catch { return ''; }
-})();
-
-const VIEWER_HTML = (exportId: string, meta: { sessionId: string; tabId?: string; durationMs: number; eventCount: number }): string => `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<title>Harness replay · ${escapeHtml(exportId)}</title>
-<link rel="stylesheet" href="/replay/static/player.css" />
-<style>
-  html, body { margin: 0; padding: 0; background: #1a1a1a; color: #eee; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
-  .meta { padding: 12px 16px; font-size: 13px; color: #aaa; border-bottom: 1px solid #333; }
-  .meta code { color: #6cf; }
-  .stage { padding: 16px; display: flex; justify-content: center; }
-  .error { padding: 24px; color: #f66; }
-</style>
-</head>
-<body>
-<div class="meta">
-  Replay <code>${escapeHtml(exportId)}</code> · session <code>${escapeHtml(meta.sessionId)}</code>${meta.tabId ? ` · tab <code>${escapeHtml(meta.tabId)}</code>` : ''} · ${meta.eventCount} events · ${Math.round(meta.durationMs / 100) / 10}s
-</div>
-<div class="stage" id="stage"></div>
-<script src="/replay/static/player.js"></script>
-<script>
-  (async function() {
-    const stage = document.getElementById('stage');
-    try {
-      const resp = await fetch(${JSON.stringify(`/replay/${exportId}.json`)});
-      if (!resp.ok) throw new Error('failed to fetch events: ' + resp.status);
-      const events = await resp.json();
-      if (!Array.isArray(events) || events.length < 2) {
-        throw new Error('export has fewer than 2 events — cannot play back');
-      }
-      // rrwebPlayer is the UMD global.
-      new rrwebPlayer({
-        target: stage,
-        props: {
-          events,
-          autoPlay: true,
-          showController: true,
-          width: Math.min(1280, window.innerWidth - 64),
-          height: Math.min(720, window.innerHeight - 120),
-        },
-      });
-    } catch (err) {
-      stage.innerHTML = '<div class="error">Replay failed: ' + (err && err.message ? String(err.message).replace(/[<>&]/g, '') : 'unknown error') + '</div>';
-      console.error('[harness replay]', err);
-    }
-  })();
-</script>
-</body>
-</html>`;
-
-function escapeHtml(s: string): string {
-    return s.replace(/[&<>"']/g, (ch) => {
-        switch (ch) {
-            case '&': return '&amp;';
-            case '<': return '&lt;';
-            case '>': return '&gt;';
-            case '"': return '&quot;';
-            default: return '&#39;';
-        }
-    });
-}
-
-function send(res: ServerResponse, status: number, contentType: string, body: string | Buffer): void {
-    res.statusCode = status;
-    res.setHeader('content-type', contentType);
-    res.setHeader('cache-control', 'no-store');
-    res.end(body);
-}
-
-/**
- * Build a handler that dispatches /replay/* requests. Returns undefined for
- * non-replay paths so the caller can chain or 404.
- */
-export function createReplayHandler(store: IStore): (req: IncomingMessage, res: ServerResponse) => boolean {
-    return (req, res) => {
-        if (!req.url) return false;
-        const url = new URL(req.url, 'http://localhost');
-        const path = url.pathname;
-        if (!path.startsWith('/replay/')) return false;
-
-        // Static assets
-        if (path === '/replay/static/player.js') {
-            if (!PLAYER_DIST) return reply500(res, 'rrweb-player not installed');
-            const file = join(PLAYER_DIST, 'index.js');
-            if (!existsSync(file)) return reply500(res, 'rrweb-player bundle missing');
-            send(res, 200, 'application/javascript; charset=utf-8', readFileSync(file));
-            return true;
-        }
-        if (path === '/replay/static/player.css') {
-            if (!PLAYER_DIST) return reply500(res, 'rrweb-player not installed');
-            const file = join(PLAYER_DIST, 'style.css');
-            if (!existsSync(file)) return reply500(res, 'rrweb-player styles missing');
-            send(res, 200, 'text/css; charset=utf-8', readFileSync(file));
-            return true;
-        }
-
-        // /replay/:id or /replay/:id.json
-        const tail = path.slice('/replay/'.length);
-        if (!tail || tail.includes('/')) {
-            send(res, 404, 'text/plain; charset=utf-8', 'Not Found');
-            return true;
-        }
-        const isJson = tail.endsWith('.json');
-        const exportId = isJson ? tail.slice(0, -'.json'.length) : tail;
-        if (!/^[A-Za-z0-9_-]+$/.test(exportId)) {
-            send(res, 400, 'text/plain; charset=utf-8', 'Invalid export id');
-            return true;
-        }
-
-        const meta = store.getExport(exportId);
-        if (!meta) {
-            send(res, 404, 'text/plain; charset=utf-8', `Unknown export: ${exportId}`);
-            return true;
-        }
-
-        if (isJson) {
-            const events = store.readExportEvents(exportId);
-            if (!events) {
-                send(res, 404, 'application/json; charset=utf-8', '{"error":"export events missing"}');
-                return true;
-            }
-            send(res, 200, 'application/json; charset=utf-8', JSON.stringify(events));
-            return true;
-        }
-
-        const html = VIEWER_HTML(exportId, {
-            sessionId: meta.sessionId,
-            tabId: meta.tabId,
-            durationMs: Math.max(0, meta.endTs - meta.startTs),
-            eventCount: meta.eventCount,
-        });
-        send(res, 200, 'text/html; charset=utf-8', html);
-        return true;
-    };
-
-    function reply500(res: ServerResponse, msg: string): true {
-        send(res, 500, 'text/plain; charset=utf-8', msg);
-        return true;
-    }
-}

package/src/sessionRouter.ts

@@ -1,119 +0,0 @@
-/**
- * SessionRouter — registry of connected peers (vite-plugin + runtime-client).
- *
- * - Project: 1 vite-plugin per project (uniqued by projectId)
- * - Tab    : N runtime-clients per project (each browser tab is one)
- *
- * Active tab heuristic: most recently active (last command or last event).
- * Caller can override via explicit tabId on every command.
- */
-
-import type {
-    PeerRole,
-    TabInfo,
-} from '@harness-fe/protocol';
-import type { Principal } from './identity.js';
-
-export interface PeerSession {
-    role: PeerRole;
-    projectId: string;
-    tabId?: string;
-    /** Caller identity behind this connection (4.0 · P1). Defaults to `local`. */
-    principal?: Principal;
-    /** Runtime-client only: identifies the page load (sessionId) this connection belongs to. */
-    sessionId?: string;
-    /** Runtime-client only: stable per-browser visitor identifier. */
-    visitorId?: string;
-    /** App-supplied user identifier propagated from HarnessScript userId prop. */
-    userId?: string;
-    /** Opaque identifier for the underlying connection. */
-    connectionId: string;
-    lastActive: number;
-    page?: { url?: string; title?: string; userAgent?: string };
-}
-
-export class SessionRouter {
-    private peers = new Map<string, PeerSession>(); // key = connectionId
-    private mostRecentTabId?: string;
-
-    register(session: Omit<PeerSession, 'lastActive'>): PeerSession {
-        const stored: PeerSession = { ...session, lastActive: Date.now() };
-        this.peers.set(session.connectionId, stored);
-        if (session.role === 'runtime-client' && session.tabId) {
-            this.mostRecentTabId = session.tabId;
-        }
-        return stored;
-    }
-
-    unregister(connectionId: string): void {
-        const peer = this.peers.get(connectionId);
-        this.peers.delete(connectionId);
-        if (peer?.tabId && this.mostRecentTabId === peer.tabId) {
-            this.mostRecentTabId = this.findFallbackTab()?.tabId;
-        }
-    }
-
-    touch(connectionId: string): void {
-        const peer = this.peers.get(connectionId);
-        if (!peer) return;
-        peer.lastActive = Date.now();
-        if (peer.role === 'runtime-client' && peer.tabId) {
-            this.mostRecentTabId = peer.tabId;
-        }
-    }
-
-    getByConnectionId(connectionId: string): PeerSession | undefined {
-        return this.peers.get(connectionId);
-    }
-
-    findVitePlugin(projectId?: string): PeerSession | undefined {
-        const candidates = [...this.peers.values()].filter(
-            (p) => p.role === 'vite-plugin' || p.role === 'webpack-plugin',
-        );
-        if (!candidates.length) return undefined;
-        if (projectId) return candidates.find((c) => c.projectId === projectId);
-        // No projectId filter — return the most recent.
-        return candidates.sort((a, b) => b.lastActive - a.lastActive)[0];
-    }
-
-    findTab(tabId?: string): PeerSession | undefined {
-        if (tabId) {
-            for (const p of this.peers.values()) {
-                if (p.role === 'runtime-client' && p.tabId === tabId) return p;
-            }
-            return undefined;
-        }
-        if (this.mostRecentTabId) {
-            return this.findTab(this.mostRecentTabId);
-        }
-        return this.findFallbackTab();
-    }
-
-    private findFallbackTab(): PeerSession | undefined {
-        const tabs = [...this.peers.values()]
-            .filter((p) => p.role === 'runtime-client' && p.tabId)
-            .sort((a, b) => b.lastActive - a.lastActive);
-        return tabs[0];
-    }
-
-    listTabs(): TabInfo[] {
-        return [...this.peers.values()]
-            .filter((p): p is PeerSession & { tabId: string } => p.role === 'runtime-client' && !!p.tabId)
-            .map((p) => ({
-                tabId: p.tabId,
-                projectId: p.projectId,
-                url: p.page?.url,
-                title: p.page?.title,
-                userAgent: p.page?.userAgent,
-                connectedAt: p.lastActive,
-            }));
-    }
-
-    listProjects(): string[] {
-        const ids = new Set<string>();
-        for (const p of this.peers.values()) {
-            if (p.role === 'vite-plugin' || p.role === 'webpack-plugin') ids.add(p.projectId);
-        }
-        return [...ids];
-    }
-}

package/src/store/JsonMemoryStore.test.ts

@@ -1,175 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import * as fc from 'fast-check';
-import { JsonMemoryStore } from './JsonMemoryStore.js';
-
-function makeStore() {
-    const dir = mkdtempSync(join(tmpdir(), 'harness-memory-test-'));
-    const store = new JsonMemoryStore(dir);
-    return { store, dir };
-}
-
-function cleanup(dir: string) {
-    try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
-}
-
-// ── Unit Tests ───────────────────────────────────────────────────────────────
-
-describe('JsonMemoryStore — unit tests', () => {
-    let dir: string;
-    let store: JsonMemoryStore;
-
-    beforeEach(() => {
-        ({ store, dir } = makeStore());
-    });
-
-    afterEach(() => {
-        cleanup(dir);
-    });
-
-    it('get returns undefined for a missing key', () => {
-        const result = store.get('proj', 'nonexistent-key');
-        expect(result).toBeUndefined();
-    });
-
-    it('list returns empty array when no entries exist', () => {
-        const result = store.list('proj');
-        expect(result).toEqual([]);
-    });
-
-    it('set stores a value and get retrieves it', () => {
-        store.set('proj', 'my-key', 'my-value');
-        const entry = store.get('proj', 'my-key');
-        expect(entry).toBeDefined();
-        expect(entry!.key).toBe('my-key');
-        expect(entry!.value).toBe('my-value');
-        expect(typeof entry!.updatedAt).toBe('number');
-        expect(entry!.updatedAt).toBeGreaterThan(0);
-    });
-
-    it('delete existing key returns { deleted: true }', () => {
-        store.set('proj', 'to-delete', 'some-value');
-        const deleted = store.delete('proj', 'to-delete');
-        expect(deleted).toBe(true);
-        expect(store.get('proj', 'to-delete')).toBeUndefined();
-    });
-
-    it('delete missing key returns { deleted: false }', () => {
-        const deleted = store.delete('proj', 'does-not-exist');
-        expect(deleted).toBe(false);
-    });
-
-    it('list returns all entries after multiple sets', () => {
-        store.set('proj', 'key-a', 'val-a');
-        store.set('proj', 'key-b', 'val-b');
-        store.set('proj', 'key-c', 'val-c');
-        const entries = store.list('proj');
-        expect(entries).toHaveLength(3);
-        const keys = entries.map((e) => e.key);
-        expect(keys).toContain('key-a');
-        expect(keys).toContain('key-b');
-        expect(keys).toContain('key-c');
-    });
-
-    it('set overwrites an existing key', () => {
-        store.set('proj', 'key', 'original');
-        store.set('proj', 'key', 'updated');
-        const entry = store.get('proj', 'key');
-        expect(entry!.value).toBe('updated');
-        const entries = store.list('proj');
-        expect(entries).toHaveLength(1);
-    });
-
-    it('entries are isolated per projectId', () => {
-        store.set('proj-a', 'key', 'value-a');
-        store.set('proj-b', 'key', 'value-b');
-        expect(store.get('proj-a', 'key')!.value).toBe('value-a');
-        expect(store.get('proj-b', 'key')!.value).toBe('value-b');
-    });
-});
-
-// ── Property-Based Tests ─────────────────────────────────────────────────────
-
-// Feature: persistence, Property 15: Memory set/get round-trip
-describe('Property 15: Memory set/get round-trip', () => {
-    it('for any key-value pair, get after set returns the written value with a valid updatedAt timestamp', () => {
-        // Validates: Requirements 7.1, 7.2, 9.1, 9.2
-        fc.assert(
-            fc.property(
-                fc.tuple(fc.string({ minLength: 1 }), fc.string()),
-                ([key, value]) => {
-                    const dir = mkdtempSync(join(tmpdir(), 'pbt-p15-'));
-                    try {
-                        const store = new JsonMemoryStore(dir);
-                        const before = Date.now();
-                        store.set('proj', key, value);
-                        const entry = store.get('proj', key);
-
-                        expect(entry).toBeDefined();
-                        expect(entry!.key).toBe(key);
-                        expect(entry!.value).toBe(value);
-                        expect(typeof entry!.updatedAt).toBe('number');
-                        expect(entry!.updatedAt).toBeGreaterThanOrEqual(before);
-                    } finally {
-                        cleanup(dir);
-                    }
-                },
-            ),
-            { numRuns: 100 },
-        );
-    });
-});
-
-// Feature: persistence, Property 14: Memory list sort order
-describe('Property 14: Memory list sort order', () => {
-    it('list returns entries sorted by updatedAt in strictly descending order', async () => {
-        // Validates: Requirements 7.4, 9.3
-        await fc.assert(
-            fc.asyncProperty(
-                fc.array(
-                    fc.tuple(fc.string({ minLength: 1 }), fc.string()),
-                    { minLength: 2 },
-                ),
-                async (pairs) => {
-                    const dir = mkdtempSync(join(tmpdir(), 'pbt-p14-'));
-                    try {
-                        const store = new JsonMemoryStore(dir);
-
-                        // Deduplicate keys to ensure distinct entries
-                        const seen = new Set<string>();
-                        const uniquePairs: Array<[string, string]> = [];
-                        for (const [k, v] of pairs) {
-                            if (!seen.has(k)) {
-                                seen.add(k);
-                                uniquePairs.push([k, v]);
-                            }
-                        }
-
-                        // Need at least 2 distinct keys to test sort order
-                        if (uniquePairs.length < 2) return;
-
-                        // Write entries with small delays to ensure distinct updatedAt values
-                        for (const [key, value] of uniquePairs) {
-                            store.set('proj', key, value);
-                            // Introduce a tiny delay to ensure distinct timestamps
-                            await new Promise((r) => setTimeout(r, 1));
-                        }
-
-                        const entries = store.list('proj');
-                        expect(entries.length).toBe(uniquePairs.length);
-
-                        // Verify strictly descending order
-                        for (let i = 1; i < entries.length; i++) {
-                            expect(entries[i - 1].updatedAt).toBeGreaterThanOrEqual(entries[i].updatedAt);
-                        }
-                    } finally {
-                        cleanup(dir);
-                    }
-                },
-            ),
-            { numRuns: 50 },
-        );
-    });
-});