@harness-fe/unplugin 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MorphixAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @harness-fe/unplugin
+
+> Unified build plugin core for [Harness-FE](https://github.com/Morphicai/harness-fe). Powers the Vite, Rspack, esbuild, and Rollup adapters.
+
+You normally do **not** install this directly — install the bundler-specific package instead:
+
+- [`@harness-fe/vite`](https://www.npmjs.com/package/@harness-fe/vite)
+- [`@harness-fe/webpack`](https://www.npmjs.com/package/@harness-fe/webpack) — **native** webpack plugin (not a unplugin adapter). Required for thread-loader compatibility.
+
+## Install (advanced)
+
+```bash
+pnpm add -D @harness-fe/unplugin
+```
+
+## Usage
+
+```ts
+import { harnessFE } from '@harness-fe/unplugin/vite';
+// or '/rspack' '/esbuild' '/rollup'
+```
+
+**Webpack users**: install `@harness-fe/webpack` instead. The `./webpack` subpath export has been removed because unplugin's webpack adapter serializes the plugin instance into loader options, which breaks `thread-loader` (the plugin holds a `compiler` reference and JSON.stringify trips on `Compiler.root`). See the changeset for details.
+
+For custom integrations, import the raw factory:
+
+```ts
+import { unplugin, unpluginFactory } from '@harness-fe/unplugin';
+```
+
+## Public API
+
+- `unplugin` — pre-built unplugin instance (call `.vite()` / `.rspack()` / etc.)
+- `unpluginFactory` — raw factory for fully custom adapters
+- `transformJsx` — JSX/TSX source transform with location attribute injection
+- `transformVueSFC` / `transformVueTemplate` — Vue SFC + template transforms
+- `createMcpClient`, `installNodeLogCapture`, `createBuildIdentity`, `appendTokenQuery` — internal building blocks used by `@harness-fe/webpack` to assemble a native plugin without going through unplugin's webpack adapter
+
+## Docs
+
+- [Root README](https://github.com/Morphicai/harness-fe#readme)
+- [Architecture](https://github.com/Morphicai/harness-fe/blob/main/ARCHITECTURE.md)
+
+## License
+
+MIT

package/dist/core.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Core unplugin definition for Harness-FE.
+ *
+ * Handles:
+ *   1. Source-aware JSX / Vue transform (data-morphix-loc / data-morphix-comp)
+ *   2. WebSocket connection to MCP server (hello handshake, command handling)
+ *   3. HTML injection of runtime client + config (Vite)
+ *   4. HMR event forwarding (Vite)
+ *
+ * Webpack users should use `@harness-fe/webpack` (a native webpack plugin)
+ * instead — the unplugin webpack adapter is incompatible with thread-loader
+ * because it serializes the plugin instance (and its compiler reference) via
+ * loader options.
+ */
+import { type UnpluginFactory } from 'unplugin';
+import type { HarnessFEOptions } from './internal/types.js';
+export type { HarnessFEOptions };
+export declare const unpluginFactory: UnpluginFactory<HarnessFEOptions | undefined>;
+export declare const unplugin: import("unplugin").UnpluginInstance<HarnessFEOptions | undefined, boolean>;

package/dist/core.js

@@ -0,0 +1,211 @@
+/**
+ * Core unplugin definition for Harness-FE.
+ *
+ * Handles:
+ *   1. Source-aware JSX / Vue transform (data-morphix-loc / data-morphix-comp)
+ *   2. WebSocket connection to MCP server (hello handshake, command handling)
+ *   3. HTML injection of runtime client + config (Vite)
+ *   4. HMR event forwarding (Vite)
+ *
+ * Webpack users should use `@harness-fe/webpack` (a native webpack plugin)
+ * instead — the unplugin webpack adapter is incompatible with thread-loader
+ * because it serializes the plugin instance (and its compiler reference) via
+ * loader options.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { relative } from 'node:path';
+import { createUnplugin } from 'unplugin';
+import { DEFAULT_WS_PORT } from '@harness-fe/protocol';
+import { transformJsx } from './transform.js';
+import { transformVueSFC, transformVueTemplate, resolveVueComponentName, getTemplateLineOffset, createVueTransformStats, formatVueTransformReport, } from './vue-transform.js';
+import { resolveProjectId } from './resolveProjectId.js';
+import { createMcpClient } from './internal/mcp-client.js';
+import { installNodeLogCapture } from './internal/log-capture.js';
+import { appendTokenQuery, createBuildIdentity } from './internal/buildIdentity.js';
+const require = createRequire(import.meta.url);
+/**
+ * Virtual module ID used to inject the runtime client into the dev page.
+ */
+const VIRTUAL_RUNTIME_ID = 'virtual:harness-fe/runtime';
+const RESOLVED_VIRTUAL_RUNTIME_ID = '\0' + VIRTUAL_RUNTIME_ID;
+export const unpluginFactory = (options = {}) => {
+    let projectId = options.projectId ?? 'unknown-project';
+    const baseMcpUrl = options.mcpUrl ?? process.env.HARNESS_FE_URL ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;
+    const token = options.token ?? process.env.HARNESS_FE_TOKEN;
+    const mcpUrl = appendTokenQuery(baseMcpUrl, token);
+    let projectRoot = process.cwd();
+    let peerRole = 'vite-plugin';
+    const componentMap = new Map();
+    let logCaptureCleanup;
+    let mcpClient;
+    // Vue 2 hardening — safeMode on by default, dry-run gated by env so
+    // legacy projects can collect a coverage report before flipping on.
+    const dryRun = process.env.HARNESS_FE_DRY_RUN === '1';
+    const vueStats = createVueTransformStats();
+    const vueOptions = {
+        safeMode: options.safeMode !== false,
+        dryRun,
+        stats: vueStats,
+    };
+    let dumpReportInstalled = false;
+    function ensureExitReport() {
+        if (dumpReportInstalled)
+            return;
+        dumpReportInstalled = true;
+        const dump = () => {
+            if (vueStats.filesAttempted === 0)
+                return;
+            process.stderr.write(formatVueTransformReport(vueStats) + '\n');
+        };
+        process.once('exit', dump);
+        process.once('SIGINT', () => { dump(); process.exit(0); });
+        process.once('SIGTERM', () => { dump(); process.exit(0); });
+    }
+    if (dryRun)
+        ensureExitReport();
+    const identity = createBuildIdentity({
+        userBuildId: options.buildId,
+        userDisplayName: options.displayName,
+    });
+    function buildMcpContext() {
+        return {
+            get projectId() { return projectId; },
+            get mcpUrl() { return mcpUrl; },
+            get token() { return token; },
+            get peerRole() { return peerRole; },
+            get parentProjectId() { return options.parentProjectId; },
+            get projectRoot() { return projectRoot; },
+            get componentMap() { return componentMap; },
+            getBuildId: () => identity.getBuildId(projectRoot),
+            getDisplayName: () => identity.getDisplayName(projectRoot),
+        };
+    }
+    function ensureMcpClient() {
+        if (!mcpClient)
+            mcpClient = createMcpClient(buildMcpContext());
+        return mcpClient;
+    }
+    // Expose for advanced usage (e.g. tests or downstream plugins inspecting state).
+    const ctx = {
+        get projectId() { return projectId; },
+        get mcpUrl() { return mcpUrl; },
+        get componentMap() { return componentMap; },
+        get isActive() { return mcpClient?.isActive ?? false; },
+    };
+    return {
+        name: 'harness-fe',
+        enforce: 'pre',
+        async buildStart() {
+            if (options.disabled)
+                return;
+            projectId = await resolveProjectId(projectRoot, options.projectId);
+        },
+        transformInclude(id) {
+            if (options.disabled)
+                return false;
+            // Accept query-string variants so we can intercept vue-loader's
+            // virtual sub-modules (`App.vue?vue&type=template…`).
+            if (!/\.([jt]sx|vue)($|\?)/.test(id))
+                return false;
+            if (id.includes('/node_modules/') || id.includes('\\node_modules\\'))
+                return false;
+            return true;
+        },
+        transform(code, id) {
+            if (options.disabled)
+                return null;
+            const queryIdx = id.indexOf('?');
+            const filePath = queryIdx === -1 ? id : id.slice(0, queryIdx);
+            const query = queryIdx === -1 ? '' : id.slice(queryIdx);
+            const rel = relative(projectRoot, filePath);
+            // Vue template virtual sub-module.
+            if (filePath.endsWith('.vue') && /[?&]vue\b/.test(query) && /[?&]type=template\b/.test(query)) {
+                let componentName;
+                let lineOffset = 0;
+                try {
+                    const sfcSource = readFileSync(filePath, 'utf-8');
+                    componentName = resolveVueComponentName(sfcSource, rel);
+                    lineOffset = getTemplateLineOffset(sfcSource, rel);
+                }
+                catch {
+                    /* fall through with no offset / no name */
+                }
+                const out = transformVueTemplate(code, rel, componentName, componentMap, lineOffset, vueOptions);
+                if (!out)
+                    return null;
+                return { code: out.code, map: out.map };
+            }
+            // Plain .vue request: full SFC transform.
+            if (filePath.endsWith('.vue') && !query) {
+                const out = transformVueSFC(code, rel, componentMap, vueOptions);
+                if (!out)
+                    return null;
+                return { code: out.code, map: out.map };
+            }
+            // Skip every other .vue sub-module (script / style).
+            if (filePath.endsWith('.vue'))
+                return null;
+            const out = transformJsx(code, rel, componentMap);
+            if (!out)
+                return null;
+            return { code: out.code, map: out.map };
+        },
+        // Vite-specific hooks
+        vite: {
+            async configResolved(config) {
+                if (options.disabled)
+                    return;
+                projectRoot = config.root ?? process.cwd();
+                projectId = await resolveProjectId(projectRoot, options.projectId);
+            },
+            configureServer(server) {
+                if (options.disabled)
+                    return;
+                const client = ensureMcpClient();
+                client.connect();
+                logCaptureCleanup = installNodeLogCapture((name, payload) => client.emitEvent(name, payload));
+                server.httpServer?.once('close', () => {
+                    logCaptureCleanup?.();
+                    logCaptureCleanup = undefined;
+                    client.disconnect();
+                });
+            },
+            resolveId(id) {
+                if (id === VIRTUAL_RUNTIME_ID)
+                    return RESOLVED_VIRTUAL_RUNTIME_ID;
+                return undefined;
+            },
+            load(id) {
+                if (id !== RESOLVED_VIRTUAL_RUNTIME_ID)
+                    return undefined;
+                const runtimeEntry = require.resolve('@harness-fe/runtime');
+                return `export * from ${JSON.stringify(runtimeEntry)};\nimport ${JSON.stringify(runtimeEntry)};`;
+            },
+            transformIndexHtml: {
+                order: 'pre',
+                handler(html) {
+                    if (options.disabled)
+                        return html;
+                    const injection = `<!-- @harness-fe injected (dev only) -->
+<script>
+window.__HARNESS_FE__ = ${JSON.stringify({ projectId, mcpUrl, buildId: identity.getBuildId(projectRoot), parentProjectId: options.parentProjectId, displayName: identity.getDisplayName(projectRoot) })};
+</script>
+<script type="module">import '${VIRTUAL_RUNTIME_ID}';</script>`;
+                    return html.replace(/<\/head>/i, `${injection}\n</head>`);
+                },
+            },
+            handleHotUpdate(hmrCtx) {
+                mcpClient?.emitEvent('hmr', {
+                    file: hmrCtx.file,
+                    type: hmrCtx.modules?.length ? 'update' : 'reload',
+                    moduleCount: hmrCtx.modules?.length ?? 0,
+                });
+                return hmrCtx.modules;
+            },
+        },
+        // Expose context for advanced usage
+        _ctx: ctx,
+    };
+};
+export const unplugin = /* #__PURE__ */ createUnplugin(unpluginFactory);

package/dist/esbuild.d.ts

@@ -0,0 +1,9 @@
+/**
+ * esbuild-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/esbuild'
+ */
+export type { HarnessFEOptions } from './core.js';
+export declare const harnessFE: (options?: import("./core.js").HarnessFEOptions | undefined) => import("unplugin").EsbuildPlugin;
+export default harnessFE;

package/dist/esbuild.js

@@ -0,0 +1,9 @@
+/**
+ * esbuild-specific export.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/esbuild'
+ */
+import { unplugin } from './core.js';
+export const harnessFE = unplugin.esbuild;
+export default harnessFE;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @harness-fe/unplugin — unified build plugin.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/vite'
+ *   import { harnessFE } from '@harness-fe/unplugin/rspack'
+ *
+ * Webpack: use @harness-fe/webpack (a native plugin — see that package).
+ *
+ * Or import the raw unplugin for custom integrations:
+ *   import { unplugin, unpluginFactory } from '@harness-fe/unplugin'
+ */
+export { unplugin, unpluginFactory, type HarnessFEOptions } from './core.js';
+export { transformJsx, type ComponentMap, type ComponentLocation, type TransformResult } from './transform.js';
+export { transformVueSFC, transformVueTemplate, resolveVueComponentName, getTemplateLineOffset, createVueTransformStats, formatVueTransformReport, type VueTransformOptions, type VueTransformResult, type VueTransformStats, } from './vue-transform.js';
+export { createMcpClient } from './internal/mcp-client.js';
+export { installNodeLogCapture } from './internal/log-capture.js';
+export { createBuildIdentity, appendTokenQuery } from './internal/buildIdentity.js';
+export type { McpClient, McpClientContext, PeerRole } from './internal/types.js';
+export type { BuildIdentity, BuildIdentityOptions } from './internal/buildIdentity.js';

package/dist/index.js

@@ -0,0 +1,20 @@
+/**
+ * @harness-fe/unplugin — unified build plugin.
+ *
+ * Usage:
+ *   import { harnessFE } from '@harness-fe/unplugin/vite'
+ *   import { harnessFE } from '@harness-fe/unplugin/rspack'
+ *
+ * Webpack: use @harness-fe/webpack (a native plugin — see that package).
+ *
+ * Or import the raw unplugin for custom integrations:
+ *   import { unplugin, unpluginFactory } from '@harness-fe/unplugin'
+ */
+export { unplugin, unpluginFactory } from './core.js';
+export { transformJsx } from './transform.js';
+export { transformVueSFC, transformVueTemplate, resolveVueComponentName, getTemplateLineOffset, createVueTransformStats, formatVueTransformReport, } from './vue-transform.js';
+// Internal building blocks — re-exported for downstream native plugins (e.g.
+// @harness-fe/webpack) that cannot use the unplugin adapter directly.
+export { createMcpClient } from './internal/mcp-client.js';
+export { installNodeLogCapture } from './internal/log-capture.js';
+export { createBuildIdentity, appendTokenQuery } from './internal/buildIdentity.js';

package/dist/internal/buildIdentity.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lazy resolvers for build-time identity metadata (buildId, displayName).
+ *
+ * Both are deferred until first read because the host bundler may not have
+ * resolved `projectRoot` at plugin instantiation time.
+ */
+export interface BuildIdentityOptions {
+    userBuildId?: string;
+    userDisplayName?: string;
+    /** Captured once so dev-mode fallback ids stay stable across re-reads. */
+    startTs?: number;
+}
+export interface BuildIdentity {
+    getBuildId(root: string): string;
+    getDisplayName(root: string): string | undefined;
+}
+export declare function createBuildIdentity(opts?: BuildIdentityOptions): BuildIdentity;
+/** Append `?token=…` (or `&token=…`) onto a URL, idempotent on empty token. */
+export declare function appendTokenQuery(url: string, token: string | undefined): string;

package/dist/internal/buildIdentity.js

@@ -0,0 +1,49 @@
+/**
+ * Lazy resolvers for build-time identity metadata (buildId, displayName).
+ *
+ * Both are deferred until first read because the host bundler may not have
+ * resolved `projectRoot` at plugin instantiation time.
+ */
+import { createRequire } from 'node:module';
+import { resolveBuildId } from '../resolveBuildId.js';
+const require = createRequire(import.meta.url);
+export function createBuildIdentity(opts = {}) {
+    const startTs = opts.startTs ?? Date.now();
+    let resolvedBuild;
+    let resolvedDisplayName = opts.userDisplayName;
+    let displayNameResolved = opts.userDisplayName !== undefined;
+    return {
+        getBuildId(root) {
+            if (resolvedBuild)
+                return resolvedBuild.buildId;
+            resolvedBuild = resolveBuildId({
+                userConfig: opts.userBuildId,
+                root,
+                startTs,
+            });
+            return resolvedBuild.buildId;
+        },
+        getDisplayName(root) {
+            if (displayNameResolved)
+                return resolvedDisplayName;
+            displayNameResolved = true;
+            try {
+                const pkg = JSON.parse(require('node:fs').readFileSync(require('node:path').join(root, 'package.json'), 'utf-8'));
+                resolvedDisplayName = pkg.name;
+            }
+            catch {
+                resolvedDisplayName = undefined;
+            }
+            return resolvedDisplayName;
+        },
+    };
+}
+/** Append `?token=…` (or `&token=…`) onto a URL, idempotent on empty token. */
+export function appendTokenQuery(url, token) {
+    if (!token)
+        return url;
+    if (/[?&]token=/.test(url))
+        return url;
+    const sep = url.includes('?') ? '&' : '?';
+    return `${url}${sep}token=${encodeURIComponent(token)}`;
+}

package/dist/internal/log-capture.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Intercepts `process.stdout.write` and `process.stderr.write` to emit
+ * `'node:log'` / `'node:err'` events to the MCP server.
+ *
+ * Returns a cleanup function that restores the original write methods.
+ */
+export declare function installNodeLogCapture(emitEvent: (name: string, payload: unknown) => void): () => void;

package/dist/internal/log-capture.js

@@ -0,0 +1,22 @@
+/**
+ * Intercepts `process.stdout.write` and `process.stderr.write` to emit
+ * `'node:log'` / `'node:err'` events to the MCP server.
+ *
+ * Returns a cleanup function that restores the original write methods.
+ */
+export function installNodeLogCapture(emitEvent) {
+    const origOut = process.stdout.write.bind(process.stdout);
+    const origErr = process.stderr.write.bind(process.stderr);
+    process.stdout.write = (chunk, ...args) => {
+        emitEvent('node:log', { text: String(chunk) });
+        return origOut(chunk, ...args);
+    };
+    process.stderr.write = (chunk, ...args) => {
+        emitEvent('node:err', { text: String(chunk) });
+        return origErr(chunk, ...args);
+    };
+    return () => {
+        process.stdout.write = origOut;
+        process.stderr.write = origErr;
+    };
+}

package/dist/internal/mcp-client.d.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP WebSocket client + command dispatch loop, factored out of the unplugin
+ * core so the native webpack plugin can reuse it without depending on the
+ * unplugin webpack adapter (which carries circular references via the plugin
+ * instance and breaks thread-loader serialization).
+ *
+ * The componentMap is supplied by the caller — vite/rspack pass their shared
+ * map; the webpack plugin passes its shared-state map keyed by pluginId.
+ */
+import type { McpClient, McpClientContext } from './types.js';
+export declare function createMcpClient(ctx: McpClientContext): McpClient;

package/dist/internal/mcp-client.js

@@ -0,0 +1,165 @@
+/**
+ * MCP WebSocket client + command dispatch loop, factored out of the unplugin
+ * core so the native webpack plugin can reuse it without depending on the
+ * unplugin webpack adapter (which carries circular references via the plugin
+ * instance and breaks thread-loader serialization).
+ *
+ * The componentMap is supplied by the caller — vite/rspack pass their shared
+ * map; the webpack plugin passes its shared-state map keyed by pluginId.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { WebSocket } from 'ws';
+import { COMMAND, frameSchema, } from '@harness-fe/protocol';
+function newId() {
+    const g = globalThis;
+    return g.crypto?.randomUUID ? g.crypto.randomUUID() : `${Date.now()}-${Math.random()}`;
+}
+export function createMcpClient(ctx) {
+    let ws;
+    let isActive = false;
+    function send(frame) {
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        try {
+            ws.send(JSON.stringify(frame));
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    async function runCommand(command, args) {
+        switch (command) {
+            case COMMAND.PROJECT_SOURCE: {
+                const a = args;
+                let file = a.file;
+                if (!file && a.component) {
+                    const locs = ctx.componentMap.get(a.component);
+                    if (!locs?.length) {
+                        throw new Error(`project.source: component "${a.component}" not found in the scan`);
+                    }
+                    file = locs[0].file;
+                }
+                if (!file) {
+                    throw new Error('project.source: pass either `file` or `component`');
+                }
+                const abs = resolve(ctx.projectRoot, file);
+                if (!abs.startsWith(ctx.projectRoot)) {
+                    throw new Error(`project.source: refusing to read outside project root: ${file}`);
+                }
+                const content = readFileSync(abs, 'utf-8');
+                return { file, content };
+            }
+            case COMMAND.PROJECT_WHERE_IS: {
+                const a = args;
+                const locs = ctx.componentMap.get(a.component);
+                if (!locs?.length) {
+                    throw new Error(`project.where_is: component "${a.component}" not found`);
+                }
+                return { component: a.component, locations: locs };
+            }
+            case COMMAND.PROJECT_MODULE_GRAPH: {
+                const components = {};
+                for (const [name, locs] of ctx.componentMap.entries()) {
+                    components[name] = locs;
+                }
+                return {
+                    components,
+                    totalFiles: new Set([...ctx.componentMap.values()].flat().map((l) => l.file)).size,
+                };
+            }
+            default:
+                throw new Error(`harness-fe: unhandled command "${command}"`);
+        }
+    }
+    async function handleCommand(frame) {
+        let response;
+        try {
+            const result = await runCommand(frame.command, frame.args);
+            response = { type: 'response', id: frame.id, ok: true, result };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            response = { type: 'response', id: frame.id, ok: false, error: { message } };
+        }
+        send(response);
+    }
+    function connect() {
+        if (isActive)
+            return;
+        isActive = true;
+        connectInternal();
+    }
+    function connectInternal() {
+        try {
+            const headers = {};
+            if (ctx.token)
+                headers.authorization = `Bearer ${ctx.token}`;
+            ws = new WebSocket(ctx.mcpUrl, { headers });
+            ws.on('open', () => {
+                const hello = {
+                    type: 'hello',
+                    id: newId(),
+                    role: ctx.peerRole,
+                    projectId: ctx.projectId,
+                    parentProjectId: ctx.parentProjectId,
+                    displayName: ctx.getDisplayName(),
+                    buildId: ctx.getBuildId(),
+                };
+                send(hello);
+            });
+            ws.on('message', (raw) => {
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw.toString());
+                }
+                catch {
+                    return;
+                }
+                const result = frameSchema.safeParse(parsed);
+                if (!result.success)
+                    return;
+                const frame = result.data;
+                if (frame.type === 'command')
+                    void handleCommand(frame);
+            });
+            ws.on('error', () => {
+                // Server may not be running — best-effort metadata only.
+            });
+            ws.on('close', () => {
+                setTimeout(() => {
+                    if (isActive)
+                        connectInternal();
+                }, 2000);
+            });
+        }
+        catch {
+            /* swallow */
+        }
+    }
+    function disconnect() {
+        isActive = false;
+        ws?.close();
+        ws = undefined;
+    }
+    function emitEvent(name, payload) {
+        const event = {
+            type: 'event',
+            id: newId(),
+            projectId: ctx.projectId,
+            buildId: ctx.getBuildId(),
+            name,
+            ts: Date.now(),
+            payload,
+        };
+        send(event);
+    }
+    return {
+        connect,
+        disconnect,
+        emitEvent,
+        get isActive() {
+            return isActive;
+        },
+    };
+}