@harness-fe/unplugin 3.2.0 → 4.0.0-next.11

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 MorphixAI
+Copyright (c) 2026 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

package/dist/core.js

@@ -20,6 +20,7 @@ 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 { resolveSoloTarget } from './soloTarget.js';
 import { createMcpClient } from './internal/mcp-client.js';
 import { installNodeLogCapture } from './internal/log-capture.js';
 import { appendTokenQuery, createBuildIdentity } from './internal/buildIdentity.js';
@@ -31,7 +32,7 @@ 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 baseMcpUrl = options.mcpUrl ?? process.env.HARNESS_FE_URL ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}/ws`;
     const token = options.token ?? process.env.HARNESS_FE_TOKEN;
     const mcpUrl = appendTokenQuery(baseMcpUrl, token);
     let projectRoot = process.cwd();
@@ -159,10 +160,23 @@ export const unpluginFactory = (options = {}) => {
                 projectRoot = config.root ?? process.cwd();
                 projectId = await resolveProjectId(projectRoot, options.projectId);
             },
-            configureServer(server) {
+            async configureServer(server) {
                 if (options.disabled)
                     return;
                 const client = ensureMcpClient();
+                // Solo: make sure a shared local gateway is up before connecting.
+                // Best-effort — if @harness-fe/cli isn't installed or the gateway
+                // is slow, the client still retries on its own.
+                const solo = resolveSoloTarget(baseMcpUrl, Boolean(token));
+                if (solo) {
+                    try {
+                        const { ensureSharedGateway } = await import('@harness-fe/cli/sharedGateway');
+                        await ensureSharedGateway({ host: solo.host, port: solo.port });
+                    }
+                    catch {
+                        /* keep going; client.connect() retries */
+                    }
+                }
                 client.connect();
                 logCaptureCleanup = installNodeLogCapture((name, payload) => client.emitEvent(name, payload));
                 server.httpServer?.once('close', () => {
@@ -189,7 +203,7 @@ export const unpluginFactory = (options = {}) => {
                         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) })};
+window.__HARNESS_FE__ = ${JSON.stringify({ projectId, mcpUrl, buildId: identity.getBuildId(projectRoot), parentProjectId: options.parentProjectId, displayName: identity.getDisplayName(projectRoot), overlay: options.overlay ?? true, consent: options.consent })};
 </script>
 <script type="module">import '${VIRTUAL_RUNTIME_ID}';</script>`;
                     return html.replace(/<\/head>/i, `${injection}\n</head>`);

package/dist/index.d.ts

@@ -16,5 +16,6 @@ export { transformVueSFC, transformVueTemplate, resolveVueComponentName, getTemp
 export { createMcpClient } from './internal/mcp-client.js';
 export { installNodeLogCapture } from './internal/log-capture.js';
 export { createBuildIdentity, appendTokenQuery } from './internal/buildIdentity.js';
+export { resolveSoloTarget } from './soloTarget.js';
 export type { McpClient, McpClientContext, PeerRole } from './internal/types.js';
 export type { BuildIdentity, BuildIdentityOptions } from './internal/buildIdentity.js';

package/dist/index.js

@@ -18,3 +18,4 @@ export { transformVueSFC, transformVueTemplate, resolveVueComponentName, getTemp
 export { createMcpClient } from './internal/mcp-client.js';
 export { installNodeLogCapture } from './internal/log-capture.js';
 export { createBuildIdentity, appendTokenQuery } from './internal/buildIdentity.js';
+export { resolveSoloTarget } from './soloTarget.js';

package/dist/internal/types.d.ts

@@ -36,6 +36,19 @@ export interface HarnessFEOptions {
      * its own output to catch any mis-aligned attribute injection.
      */
     safeMode?: boolean;
+    /**
+     * Show the in-page "H" overlay (default: true). Set to false to hide the
+     * overlay in production dogfood scenarios — data capture is unaffected.
+     */
+    overlay?: boolean;
+    /**
+     * Browser consent policy. When set, takes priority over the gateway
+     * hello.ack consent mode.
+     *   'off'     — no user prompt, control commands run freely (default)
+     *   'session' — user grants once per page-load
+     *   'always'  — prompt before every control command
+     */
+    consent?: 'off' | 'session' | 'always';
 }
 /**
  * Context handed to the MCP client. Getters keep the values fresh as the

package/dist/soloTarget.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Decide whether this build is "solo" (a loopback target, no token) and, if so,
+ * the (host, port) on which the dev server should auto-spawn / reuse a shared
+ * gateway. Returns null for "team" (an explicit token, or a non-loopback /
+ * unparseable target) — in which case the plugin must NOT spawn anything; that
+ * gateway is deployed and owned elsewhere.
+ */
+export declare function resolveSoloTarget(mcpUrl: string, hasToken: boolean): {
+    host: string;
+    port: number;
+} | null;

package/dist/soloTarget.js

@@ -0,0 +1,23 @@
+import { DEFAULT_WS_PORT } from '@harness-fe/protocol';
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+/**
+ * Decide whether this build is "solo" (a loopback target, no token) and, if so,
+ * the (host, port) on which the dev server should auto-spawn / reuse a shared
+ * gateway. Returns null for "team" (an explicit token, or a non-loopback /
+ * unparseable target) — in which case the plugin must NOT spawn anything; that
+ * gateway is deployed and owned elsewhere.
+ */
+export function resolveSoloTarget(mcpUrl, hasToken) {
+    if (hasToken)
+        return null;
+    try {
+        const u = new URL(mcpUrl);
+        if (LOOPBACK_HOSTS.has(u.hostname)) {
+            return { host: u.hostname, port: u.port ? Number(u.port) : DEFAULT_WS_PORT };
+        }
+    }
+    catch {
+        /* unparseable URL → treat as team (don't spawn) */
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-fe/unplugin",
-  "version": "3.2.0",
+  "version": "4.0.0-next.11",
   "description": "Unified build plugin for Harness-FE. Supports Vite, Rspack, esbuild, and Rollup via unplugin. Webpack users should use @harness-fe/webpack (native plugin) instead.",
   "type": "module",
   "license": "MIT",
@@ -44,15 +44,18 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@babel/parser": "^7.29.3",
-    "@babel/traverse": "^7.29.0",
-    "@babel/types": "^7.29.0",
-    "@vue/compiler-dom": "^3.4.0",
-    "@vue/compiler-sfc": "^3.4.0",
+    "@babel/parser": "^7.29.7",
+    "@babel/traverse": "^7.29.7",
+    "@babel/types": "^7.29.7",
+    "@vue/compiler-dom": "^3.5.35",
+    "@vue/compiler-sfc": "^3.5.35",
     "magic-string": "^0.30.21",
     "unplugin": "^2.3.2",
-    "ws": "^8.18.0",
-    "@harness-fe/protocol": "3.2.0"
+    "ws": "^8.21.0",
+    "@harness-fe/protocol": "4.0.0-next.8"
+  },
+  "optionalDependencies": {
+    "@harness-fe/cli": "4.0.0-next.11"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.28.0",

package/src/core.ts

@@ -30,6 +30,7 @@ import {
     type VueTransformOptions,
 } from './vue-transform.js';
 import { resolveProjectId } from './resolveProjectId.js';
+import { resolveSoloTarget } from './soloTarget.js';
 import { createMcpClient } from './internal/mcp-client.js';
 import { installNodeLogCapture } from './internal/log-capture.js';
 import { appendTokenQuery, createBuildIdentity } from './internal/buildIdentity.js';
@@ -48,7 +49,7 @@ export type { HarnessFEOptions };
 export const unpluginFactory: UnpluginFactory<HarnessFEOptions | undefined> = (options = {}) => {
     let projectId = options.projectId ?? 'unknown-project';
     const baseMcpUrl =
-        options.mcpUrl ?? process.env.HARNESS_FE_URL ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}`;
+        options.mcpUrl ?? process.env.HARNESS_FE_URL ?? `ws://127.0.0.1:${DEFAULT_WS_PORT}/ws`;
     const token = options.token ?? process.env.HARNESS_FE_TOKEN;
     const mcpUrl = appendTokenQuery(baseMcpUrl, token);
     let projectRoot = process.cwd();
@@ -104,6 +105,7 @@ export const unpluginFactory: UnpluginFactory<HarnessFEOptions | undefined> = (o
         return mcpClient;
     }
 
+
     // Expose for advanced usage (e.g. tests or downstream plugins inspecting state).
     const ctx = {
         get projectId() { return projectId; },
@@ -176,9 +178,21 @@ export const unpluginFactory: UnpluginFactory<HarnessFEOptions | undefined> = (o
                 projectId = await resolveProjectId(projectRoot, options.projectId);
             },
 
-            configureServer(server: any) {
+            async configureServer(server: any) {
                 if (options.disabled) return;
                 const client = ensureMcpClient();
+                // Solo: make sure a shared local gateway is up before connecting.
+                // Best-effort — if @harness-fe/cli isn't installed or the gateway
+                // is slow, the client still retries on its own.
+                const solo = resolveSoloTarget(baseMcpUrl, Boolean(token));
+                if (solo) {
+                    try {
+                        const { ensureSharedGateway } = await import('@harness-fe/cli/sharedGateway');
+                        await ensureSharedGateway({ host: solo.host, port: solo.port });
+                    } catch {
+                        /* keep going; client.connect() retries */
+                    }
+                }
                 client.connect();
                 logCaptureCleanup = installNodeLogCapture((name, payload) => client.emitEvent(name, payload));
                 server.httpServer?.once('close', () => {
@@ -205,7 +219,7 @@ export const unpluginFactory: UnpluginFactory<HarnessFEOptions | undefined> = (o
                     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) })};
+window.__HARNESS_FE__ = ${JSON.stringify({ projectId, mcpUrl, buildId: identity.getBuildId(projectRoot), parentProjectId: options.parentProjectId, displayName: identity.getDisplayName(projectRoot), overlay: options.overlay ?? true, consent: options.consent })};
 </script>
 <script type="module">import '${VIRTUAL_RUNTIME_ID}';</script>`;
                     return html.replace(/<\/head>/i, `${injection}\n</head>`);

package/src/index.ts

@@ -30,5 +30,6 @@ export {
 export { createMcpClient } from './internal/mcp-client.js';
 export { installNodeLogCapture } from './internal/log-capture.js';
 export { createBuildIdentity, appendTokenQuery } from './internal/buildIdentity.js';
+export { resolveSoloTarget } from './soloTarget.js';
 export type { McpClient, McpClientContext, PeerRole } from './internal/types.js';
 export type { BuildIdentity, BuildIdentityOptions } from './internal/buildIdentity.js';

package/src/internal/types.ts

@@ -39,6 +39,19 @@ export interface HarnessFEOptions {
      * its own output to catch any mis-aligned attribute injection.
      */
     safeMode?: boolean;
+    /**
+     * Show the in-page "H" overlay (default: true). Set to false to hide the
+     * overlay in production dogfood scenarios — data capture is unaffected.
+     */
+    overlay?: boolean;
+    /**
+     * Browser consent policy. When set, takes priority over the gateway
+     * hello.ack consent mode.
+     *   'off'     — no user prompt, control commands run freely (default)
+     *   'session' — user grants once per page-load
+     *   'always'  — prompt before every control command
+     */
+    consent?: 'off' | 'session' | 'always';
 }
 
 /**

package/src/soloTarget.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { DEFAULT_WS_PORT } from '@harness-fe/protocol';
+import { resolveSoloTarget } from './soloTarget.js';
+
+describe('resolveSoloTarget', () => {
+    it('loopback + no token → spawn target with explicit port', () => {
+        expect(resolveSoloTarget('ws://127.0.0.1:47729/ws', false)).toEqual({ host: '127.0.0.1', port: 47729 });
+    });
+
+    it('localhost host is loopback too', () => {
+        expect(resolveSoloTarget('ws://localhost:48000/ws', false)).toEqual({ host: 'localhost', port: 48000 });
+    });
+
+    it('no port in URL → DEFAULT_WS_PORT', () => {
+        expect(resolveSoloTarget('ws://127.0.0.1/ws', false)).toEqual({ host: '127.0.0.1', port: DEFAULT_WS_PORT });
+    });
+
+    it('has token → null (team: never auto-spawn)', () => {
+        expect(resolveSoloTarget('ws://127.0.0.1:47729/ws', true)).toBeNull();
+    });
+
+    it('non-loopback host → null (team: remote gateway owned elsewhere)', () => {
+        expect(resolveSoloTarget('ws://10.0.0.5:9000/ws', false)).toBeNull();
+    });
+
+    it('unparseable URL → null', () => {
+        expect(resolveSoloTarget('not a url', false)).toBeNull();
+    });
+});

package/src/soloTarget.ts

@@ -0,0 +1,26 @@
+import { DEFAULT_WS_PORT } from '@harness-fe/protocol';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+
+/**
+ * Decide whether this build is "solo" (a loopback target, no token) and, if so,
+ * the (host, port) on which the dev server should auto-spawn / reuse a shared
+ * gateway. Returns null for "team" (an explicit token, or a non-loopback /
+ * unparseable target) — in which case the plugin must NOT spawn anything; that
+ * gateway is deployed and owned elsewhere.
+ */
+export function resolveSoloTarget(
+    mcpUrl: string,
+    hasToken: boolean,
+): { host: string; port: number } | null {
+    if (hasToken) return null;
+    try {
+        const u = new URL(mcpUrl);
+        if (LOOPBACK_HOSTS.has(u.hostname)) {
+            return { host: u.hostname, port: u.port ? Number(u.port) : DEFAULT_WS_PORT };
+        }
+    } catch {
+        /* unparseable URL → treat as team (don't spawn) */
+    }
+    return null;
+}