hoversource 1.0.0

package/dist/patcher/ReactRuntimePatcher.js

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+import { recordPatchState, removePatchState } from "../utils/patchState.js";
+const patchedReactRuntimesList = [];
+function patchVendoredReactRuntime(content, relPath, projectRoot) {
+    const exportsIdx = content.indexOf("module.exports");
+    if (exportsIdx === -1) {
+        return null;
+    }
+    const equalsIdx = content.indexOf("=", exportsIdx);
+    const endIdx = content.indexOf(";", exportsIdx);
+    if (equalsIdx === -1 || endIdx === -1 || equalsIdx >= endIdx) {
+        return null;
+    }
+    const originalExpr = content.slice(equalsIdx + 1, endIdx).trim();
+    const isDev = relPath.includes("dev");
+    let wrappedContent = "";
+    if (isDev) {
+        wrappedContent = `
+const original = ${originalExpr};
+exports.Fragment = original.Fragment;
+exports.jsxDEV = function(type, config, maybeKey, isStaticChildren, source, self) {
+  globalThis.__HOVERSOURCE_INJECT_SOURCE__(type, config, source);
+  return original.jsxDEV(type, config, maybeKey, isStaticChildren, source, self);
+};
+`;
+    }
+    else {
+        wrappedContent = `
+const original = ${originalExpr};
+exports.Fragment = original.Fragment;
+exports.jsx = function(type, config, maybeKey, ...args) {
+  globalThis.__HOVERSOURCE_INJECT_SOURCE__(type, config);
+  return original.jsx.call(this, type, config, maybeKey, ...args);
+};
+exports.jsxs = function(type, config, maybeKey, ...args) {
+  globalThis.__HOVERSOURCE_INJECT_SOURCE__(type, config);
+  return original.jsxs.call(this, type, config, maybeKey, ...args);
+};
+`;
+    }
+    return (content.includes('"use strict";') ? '"use strict";\n' : "") + `
+// HoverSource Injection Patch
+if (!globalThis.__HOVERSOURCE_INJECT_SOURCE__) {
+  globalThis.__HOVERSOURCE_INJECT_SOURCE__ = (function() {
+    const path = require("path");
+    let ssrLogCount = 0;
+    
+    function getJSXSourceLocation(type) {
+      const err = new Error();
+      const stack = err.stack || "";
+
+      if (typeof window === "undefined" && ssrLogCount < 200) {
+        ssrLogCount++;
+        try {
+          const lines = stack.split("\\n");
+          for (let i = 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (!line) continue;
+            const normalizedLine = line.replace(/\\\\/g, "/");
+            const isFramework = 
+              line.includes("jsxDEV") ||
+              line.includes("jsxsDEV") ||
+              line.includes("node:internal") ||
+              line.includes("Module._compile") ||
+              line.includes("next-dev-server") ||
+              /node_modules[\\/_]react[\\/_]/i.test(normalizedLine) ||
+              /node_modules[\\/_]react-dom[\\/_]/i.test(normalizedLine) ||
+              /node_modules[\\/_]next[\\/_]/i.test(normalizedLine) ||
+              /node_modules[\\/_]scheduler[\\/_]/i.test(normalizedLine) ||
+              line.includes("react-jsx-dev-runtime") ||
+              line.includes("react-jsx-runtime");
+
+            if (isFramework) {
+              continue;
+            }
+            const match = line.match(/(?:at\\\\s+.*?\\\\s+\\\\(|at\\\\s+)(.*?):(\\\\d+):(\\\\d+)\\\\)?$/);
+            if (match) {
+              return {
+                fileName: match[1],
+                lineNumber: parseInt(match[2], 10),
+                columnNumber: parseInt(match[3], 10)
+              };
+            }
+          }
+        } catch {}
+      }
+      return null;
+    }
+
+    return function(type, config, source) {
+      if (!config || typeof type !== "string") return;
+      if (config["data-hoversource-loc"]) return;
+      
+      const loc = source || getJSXSourceLocation(type);
+      if (loc) {
+        let filePath = loc.fileName || "";
+        try {
+          if (path.isAbsolute(filePath)) {
+            filePath = path.relative(process.cwd(), filePath).replace(/\\\\/g, "/");
+          }
+        } catch {}
+        config["data-hoversource-loc"] = \`\${filePath}:\${loc.lineNumber}:\${loc.columnNumber}\`;
+      }
+    };
+  })();
+}
+${wrappedContent}
+`;
+}
+function patchSingleReactRuntime(fullPath, relPath, projectRoot) {
+    try {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        if (content.includes("HoverSource Injection Patch")) {
+            return;
+        }
+        let newContent = content;
+        if (relPath.includes("vendored")) {
+            const patched = patchVendoredReactRuntime(content, relPath, projectRoot);
+            if (patched) {
+                newContent = patched;
+            }
+        }
+        else {
+            // 1. For anonymous function exports, prepend injection as the first statement in the body
+            newContent = newContent.replace(/exports\.jsxDEV\s*=\s*function\s*\(\s*type,\s*config,\s*maybeKey,\s*isStaticChildren\s*\)\s*\{/g, "exports.jsxDEV = function(type, config, maybeKey, isStaticChildren) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(type, config, arguments[4]);");
+            newContent = newContent.replace(/exports\.jsx\s*=\s*function\s*\(\s*type,\s*config,\s*maybeKey\s*\)\s*\{/g, "exports.jsx = function(type, config, maybeKey) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(type, config);");
+            newContent = newContent.replace(/exports\.jsxs\s*=\s*function\s*\(\s*type,\s*config,\s*maybeKey\s*\)\s*\{/g, "exports.jsxs = function(type, config, maybeKey) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(type, config);");
+            // 2. For variable assignments, replace with top-level wrappers at module scope
+            newContent = newContent.replace("exports.jsxDEV = jsxDEV$1;", "exports.jsxDEV = function(t, c, k, s, ...args) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(t, c, s); return jsxDEV$1(t, c, k, s, ...args); };");
+            newContent = newContent.replace("exports.jsxDEV = jsxDEV;", "exports.jsxDEV = function(t, c, k, s, ...args) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(t, c, s); return jsxDEV(t, c, k, s, ...args); };");
+            newContent = newContent.replace("exports.jsx = jsx;", "exports.jsx = function(t, c, k, ...args) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(t, c); return jsx(t, c, k, ...args); };");
+            newContent = newContent.replace("exports.jsx = jsxWithValidationDynamic;", "exports.jsx = function(t, c, k, ...args) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(t, c); return jsxWithValidationDynamic(t, c, k, ...args); };");
+            newContent = newContent.replace("exports.jsxs = jsxs;", "exports.jsxs = function(t, c, k, ...args) { globalThis.__HOVERSOURCE_INJECT_SOURCE__(t, c); return jsxs(t, c, k, ...args); };");
+            // 3. Append the global helper block to the end of the file
+            newContent = newContent + `
+// HoverSource Injection Patch
+globalThis.__HOVERSOURCE_INJECT_SOURCE__ = (function() {
+  const path = require("path");
+  let ssrLogCount = 0;
+  
+  function getJSXSourceLocation(type) {
+    const err = new Error();
+    const stack = err.stack || "";
+
+    if (typeof window === "undefined" && ssrLogCount < 200) {
+      ssrLogCount++;
+      try {
+        const lines = stack.split("\\n");
+        for (let i = 1; i < lines.length; i++) {
+          const line = lines[i];
+          if (!line) continue;
+          const normalizedLine = line.replace(/\\\\/g, "/");
+          const isFramework = 
+            line.includes("jsxDEV") ||
+            line.includes("jsxsDEV") ||
+            line.includes("node:internal") ||
+            line.includes("Module._compile") ||
+            line.includes("next-dev-server") ||
+            /node_modules[\\/_]react[\\/_]/i.test(normalizedLine) ||
+            /node_modules[\\/_]react-dom[\\/_]/i.test(normalizedLine) ||
+            /node_modules[\\/_]next[\\/_]/i.test(normalizedLine) ||
+            /node_modules[\\/_]scheduler[\\/_]/i.test(normalizedLine) ||
+            line.includes("react-jsx-dev-runtime") ||
+            line.includes("react-jsx-runtime");
+
+          if (isFramework) {
+            continue;
+          }
+          const match = line.match(/(?:at\\\\s+.*?\\\\s+\\\\(|at\\\\s+)(.*?):(\\\\d+):(\\\\d+)\\\\)?$/);
+          if (match) {
+            return {
+              fileName: match[1],
+              lineNumber: parseInt(match[2], 10),
+              columnNumber: parseInt(match[3], 10)
+            };
+          }
+        }
+      } catch {}
+    }
+    return null;
+  }
+
+  return function(type, config, source) {
+    if (!config || typeof type !== "string") return;
+    if (config["data-hoversource-loc"]) return;
+    
+    const loc = source || getJSXSourceLocation(type);
+    if (loc) {
+      let filePath = loc.fileName || "";
+      try {
+        if (path.isAbsolute(filePath)) {
+          filePath = path.relative(process.cwd(), filePath).replace(/\\\\/g, "/");
+        }
+      } catch {}
+      config["data-hoversource-loc"] = \`\${filePath}:\${loc.lineNumber}:\${loc.columnNumber}\`;
+    }
+  };
+})();
+`;
+        }
+        if (newContent !== content) {
+            recordPatchState(fullPath, content);
+            patchedReactRuntimesList.push({ path: fullPath, originalContent: content });
+            fs.writeFileSync(fullPath, newContent, "utf-8");
+            console.log(`[HoverSource] Temporarily patched React development runtime on disk: ${path.relative(projectRoot, fullPath)}`);
+        }
+    }
+    catch (err) {
+        console.warn(`[HoverSource] Failed to patch React runtime in ${path.relative(projectRoot, fullPath)}:`, err.message);
+    }
+}
+export class ReactRuntimePatcher {
+    patch(projectRoot) {
+        process.once("exit", () => this.restore());
+        const searchDirs = [
+            projectRoot,
+            path.join(projectRoot, "apps/web")
+        ];
+        const relativePaths = [
+            "node_modules/react/cjs/react-jsx-dev-runtime.development.js",
+            "node_modules/next/dist/compiled/react/cjs/react-jsx-dev-runtime.development.js",
+            "node_modules/next/dist/compiled/react-experimental/cjs/react-jsx-dev-runtime.development.js",
+            "node_modules/next/dist/compiled/react/cjs/react-jsx-dev-runtime.react-server.development.js",
+            "node_modules/next/dist/compiled/react-experimental/cjs/react-jsx-dev-runtime.react-server.development.js",
+            "node_modules/react/cjs/react-jsx-runtime.development.js",
+            "node_modules/next/dist/compiled/react/cjs/react-jsx-runtime.development.js",
+            "node_modules/next/dist/compiled/react-experimental/cjs/react-jsx-runtime.development.js",
+            "node_modules/next/dist/compiled/react/cjs/react-jsx-runtime.react-server.development.js",
+            "node_modules/next/dist/compiled/react-experimental/cjs/react-jsx-runtime.react-server.development.js",
+            // Next.js App Router vendored runtimes
+            "node_modules/next/dist/server/route-modules/app-page/vendored/rsc/react-jsx-dev-runtime.js",
+            "node_modules/next/dist/server/route-modules/app-page/vendored/rsc/react-jsx-runtime.js",
+            "node_modules/next/dist/server/route-modules/app-page/vendored/ssr/react-jsx-dev-runtime.js",
+            "node_modules/next/dist/server/route-modules/app-page/vendored/ssr/react-jsx-runtime.js",
+            "node_modules/next/dist/esm/server/route-modules/app-page/vendored/rsc/react-jsx-dev-runtime.js",
+            "node_modules/next/dist/esm/server/route-modules/app-page/vendored/rsc/react-jsx-runtime.js",
+            "node_modules/next/dist/esm/server/route-modules/app-page/vendored/ssr/react-jsx-dev-runtime.js",
+            "node_modules/next/dist/esm/server/route-modules/app-page/vendored/ssr/react-jsx-runtime.js"
+        ];
+        for (const dir of searchDirs) {
+            for (const relPath of relativePaths) {
+                const fullPath = path.resolve(dir, relPath);
+                if (fs.existsSync(fullPath)) {
+                    patchSingleReactRuntime(fullPath, relPath, projectRoot);
+                }
+            }
+        }
+    }
+    restore() {
+        for (const file of patchedReactRuntimesList) {
+            try {
+                fs.writeFileSync(file.path, file.originalContent, "utf-8");
+                removePatchState(file.path);
+                console.log(`[HoverSource] Restored React development runtime: ${file.path}`);
+            }
+            catch (err) {
+                console.error(`[HoverSource] Failed to restore React runtime ${file.path}:`, err.message);
+            }
+        }
+        patchedReactRuntimesList.length = 0;
+    }
+}

package/dist/patcher/types.d.ts

@@ -0,0 +1,4 @@
+export interface RuntimePatcher {
+    patch(projectRoot: string): void;
+    restore(): void;
+}

package/dist/patcher/types.js

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

package/dist/pipeline.d.ts

@@ -0,0 +1,14 @@
+export interface ProxyPipelineOptions {
+    overlayScriptUrl: string;
+}
+export declare class ProxyResponsePipeline {
+    /**
+     * Checks if the response content type needs to be transformed (i.e. is HTML).
+     */
+    shouldTransform(contentType: string): boolean;
+    /**
+     * Decompresses the response body based on contentEncoding, injects the overlay script,
+     * and returns the transformed uncompressed Buffer.
+     */
+    transform(body: Buffer, contentEncoding: string, options: ProxyPipelineOptions): Buffer;
+}

package/dist/pipeline.js

@@ -0,0 +1,45 @@
+import zlib from "node:zlib";
+export class ProxyResponsePipeline {
+    /**
+     * Checks if the response content type needs to be transformed (i.e. is HTML).
+     */
+    shouldTransform(contentType) {
+        return contentType.toLowerCase().includes("text/html");
+    }
+    /**
+     * Decompresses the response body based on contentEncoding, injects the overlay script,
+     * and returns the transformed uncompressed Buffer.
+     */
+    transform(body, contentEncoding, options) {
+        if (body.length === 0) {
+            return body;
+        }
+        let buffer = body;
+        const encoding = (contentEncoding || "").toLowerCase().trim();
+        try {
+            if (encoding.includes("gzip")) {
+                buffer = zlib.gunzipSync(buffer);
+            }
+            else if (encoding.includes("deflate")) {
+                buffer = zlib.inflateSync(buffer);
+            }
+            else if (encoding.includes("br")) {
+                buffer = zlib.brotliDecompressSync(buffer);
+            }
+        }
+        catch (err) {
+            console.error(`[HoverSource Proxy] Failed to decompress body:`, err.message);
+        }
+        let html = buffer.toString("utf-8");
+        // Strip integrity attributes to avoid SRI mismatches when injecting or modifying scripts/styles
+        html = html.replace(/\sintegrity\s*=\s*(?:"[^"]*"|'[^']*'|[^'"\s>]+)/gi, "");
+        const injection = `<script src="${options.overlayScriptUrl}"></script>`;
+        if (html.includes("</body>")) {
+            html = html.replace("</body>", `${injection}\n</body>`);
+        }
+        else {
+            html += `\n${injection}`;
+        }
+        return Buffer.from(html, "utf-8");
+    }
+}

package/dist/port.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Port resolution module for HoverSource CLI.
+ *
+ * Consolidates all port-checking, port-finding, and conflict-resolution logic.
+ * The two main entry points are:
+ *   - `resolveDevServerPort()` — ensures the dev port is free and returns env/args to inject
+ *   - `resolveAllPorts()` — one-shot collision-free resolution of all ports HS needs
+ */
+export interface DevServerPortResult {
+    /** The port the dev server will actually listen on. */
+    port: number;
+    /** Env vars to inject into the spawned process (e.g. { PORT: "5174" }). */
+    env: Record<string, string>;
+    /** Extra CLI args for frameworks that prefer --port (appended to spawn args). */
+    extraArgs: string[];
+}
+export interface PortPlan {
+    companionPort: number;
+    devServerPort: number;
+    debugPort: number;
+    proxyPort: number;
+    /** Env vars to inject into the spawned dev server process. */
+    devServerEnv: Record<string, string>;
+    /** Extra CLI args to append to the spawned dev server command. */
+    devServerExtraArgs: string[];
+}
+export declare function probeHostPort(port: number, host: string): Promise<boolean>;
+export declare function isPortFree(port: number): Promise<boolean>;
+export declare function findFreePort(startPort: number, excludePorts?: number | number[], maxPort?: number): Promise<number>;
+export declare function getPidUsingPort(port: number): Promise<number | undefined>;
+export declare function getProcessName(pid: number): Promise<string | undefined>;
+export declare function killProcess(pid: number, port: number): Promise<boolean>;
+export declare function askQuestion(query: string): Promise<string>;
+export declare function isZombieOfProject(pid: number, projectRoot: string): Promise<boolean>;
+/**
+ * If the requested port is occupied by another HoverSource instance, tell it
+ * to shut down and wait for the port to free up so we can reuse it.
+ * Returns the port we should actually bind to.
+ */
+export declare function resolveCompanionPort(requestedPort: number, targetPort?: number): Promise<number>;
+/**
+ * Ensures the dev server port is free before the app launches.
+ *
+ * Two distinct strategies based on mode:
+ * - **web**: Shift to next free port + inject PORT/VITE_PORT env vars. Works because
+ *   web frameworks read these env vars to determine which port to bind.
+ * - **electron**: MUST free the original port. Port shifting won't work because Electron
+ *   projects embed the dev server inside concurrently/scripts with hardcoded port references
+ *   (e.g. VITE_DEV_SERVER_URL=http://localhost:5173). For Electron, the function will:
+ *   1. Auto-kill zombie processes from the same project
+ *   2. Prompt to kill any other blocker (default: YES, since there's no alternative)
+ *   3. In non-interactive mode, auto-kill the blocker
+ */
+export declare function resolveDevServerPort(opts: {
+    projectRoot: string;
+    execCommand: string;
+    expectedPort: number;
+    mode: "web" | "electron";
+    autoResolve: boolean;
+    /** Ports already claimed by other HS subsystems — will be excluded from candidates. */
+    excludePorts?: number[];
+}): Promise<DevServerPortResult>;
+/**
+ * Resolves all ports HS needs in one call. Guarantees no collisions between
+ * companion, dev server, debug, and proxy ports. Returns a PortPlan.
+ */
+export declare function resolveAllPorts(opts: {
+    projectRoot: string;
+    execCommand?: string;
+    requestedCompanionPort: number;
+    expectedDevPort: number;
+    debugPort: number;
+    requestedProxyPort?: number;
+    mode: "web" | "electron";
+    autoResolve: boolean;
+}): Promise<PortPlan>;