hoversource 1.0.0

package/dist/bootstrap.d.ts

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

package/dist/bootstrap.js

@@ -0,0 +1,75 @@
+import Module, { register } from "node:module";
+import { pathToFileURL, fileURLToPath } from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Dynamically write the CJS wrapper to dist/ if it doesn't exist (since tsc doesn't transpile .cjs files)
+const cjsWrapperPath = path.resolve(__dirname, "./custom-jsx-dev-runtime-cjs.cjs");
+if (!fs.existsSync(cjsWrapperPath)) {
+    const cjsContent = `const path = require("path");
+const wrapperPath = module.filename;
+const originalPath = (globalThis.__HOVERSOURCE_ORIGINAL_CJS_RUNTIMES__ && globalThis.__HOVERSOURCE_ORIGINAL_CJS_RUNTIMES__[wrapperPath]) || "react/jsx-dev-runtime";
+const original = require(originalPath);
+
+exports.Fragment = original.Fragment;
+
+exports.jsxDEV = function(type, props, key, isStaticChildren, source, self) {
+  if (typeof window === "undefined" && source && props && typeof type === "string") {
+    let filePath = source.fileName || "";
+    try {
+      const relative = path.relative(process.cwd(), filePath).replace(/\\\\/g, "/");
+      filePath = relative;
+    } catch {}
+
+    props["data-hoversource-loc"] = \`\${filePath}:\${source.lineNumber}:\${source.columnNumber}\`;
+  }
+  return original.jsxDEV(type, props, key, isStaticChildren, source, self);
+};
+
+exports.jsxsDEV = original.jsxsDEV || exports.jsxDEV;
+`;
+    fs.writeFileSync(cjsWrapperPath, cjsContent, "utf-8");
+}
+// 1. Register ESM loader
+try {
+    const loaderUrl = pathToFileURL(path.resolve(__dirname, "./loader.js")).href;
+    register(loaderUrl);
+}
+catch (err) {
+    if (process.env.DEBUG) {
+        console.debug("[HoverSource Bootstrap] Failed to register ESM loader:", err.message);
+    }
+}
+// 2. Patch CommonJS _resolveFilename
+try {
+    const originalResolve = Module._resolveFilename;
+    // Registry for tracking original runtime paths mapped to the wrapper path
+    globalThis.__HOVERSOURCE_ORIGINAL_CJS_RUNTIMES__ = globalThis.__HOVERSOURCE_ORIGINAL_CJS_RUNTIMES__ || {};
+    Module._resolveFilename = function (request, parent, isMain, options) {
+        // Check for recursion guard: if parent is the CJS wrapper itself, do not redirect
+        const wrapperPath = path.resolve(__dirname, "./custom-jsx-dev-runtime-cjs.cjs");
+        const parentFile = parent?.filename || "";
+        if (parentFile === wrapperPath) {
+            return originalResolve.apply(this, arguments);
+        }
+        const isTarget = request === "react/jsx-dev-runtime" ||
+            request.endsWith("/react/jsx-dev-runtime") ||
+            request.replaceAll("\\", "/").includes("react/jsx-dev-runtime") ||
+            request.includes("next/dist/compiled/react/jsx-dev-runtime");
+        if (isTarget) {
+            try {
+                const originalPath = originalResolve.apply(this, arguments);
+                globalThis.__HOVERSOURCE_ORIGINAL_CJS_RUNTIMES__[wrapperPath] = originalPath;
+                return wrapperPath;
+            }
+            catch { }
+        }
+        return originalResolve.apply(this, arguments);
+    };
+}
+catch (err) {
+    if (process.env.DEBUG) {
+        console.debug("[HoverSource Bootstrap] Failed to patch CJS resolver:", err.message);
+    }
+}

package/dist/cert-ca.d.ts

@@ -0,0 +1,19 @@
+import { SslCredentials } from "./cert.js";
+/**
+ * Returns the path/command for openssl.
+ * Fallbacks to Git for Windows openssl path if default openssl is not in the system path.
+ */
+export declare function getOpensslCommand(): string;
+/**
+ * Ensures the Root CA certificate exists and is registered in the OS Trusted Root store.
+ * Returns the path to the CA key and certificate files.
+ */
+export declare function ensureRootCa(): {
+    caKeyPath: string;
+    caCertPath: string;
+};
+/**
+ * Generates and signs a local domain SSL certificate for the specified target host
+ * using the HoverSource Root CA.
+ */
+export declare function getOrCreateCaSignedCert(targetHost: string): SslCredentials;

package/dist/cert-ca.js

@@ -0,0 +1,180 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+/**
+ * Returns the path/command for openssl.
+ * Fallbacks to Git for Windows openssl path if default openssl is not in the system path.
+ */
+export function getOpensslCommand() {
+    if (process.platform === "win32") {
+        try {
+            execFileSync("openssl", ["version"], { stdio: "ignore" });
+            return "openssl";
+        }
+        catch {
+            const gitOpenssl = String.raw `C:\Program Files\Git\usr\bin\openssl.exe`;
+            if (fs.existsSync(gitOpenssl)) {
+                return gitOpenssl;
+            }
+        }
+    }
+    return "openssl";
+}
+/**
+ * Ensures the Root CA certificate exists and is registered in the OS Trusted Root store.
+ * Returns the path to the CA key and certificate files.
+ */
+export function ensureRootCa() {
+    const sslDir = path.join(os.homedir(), ".hoversource", "ssl");
+    if (!fs.existsSync(sslDir)) {
+        fs.mkdirSync(sslDir, { recursive: true });
+    }
+    const caKeyPath = path.join(sslDir, "ca.key");
+    const caCertPath = path.join(sslDir, "ca.pem");
+    const openssl = getOpensslCommand();
+    // 1. Generate Root CA files if they don't exist
+    if (!fs.existsSync(caKeyPath) || !fs.existsSync(caCertPath)) {
+        try {
+            console.log(`[HoverSource SSL CA] Generating Root CA keys in ${sslDir}...`);
+            execFileSync(openssl, [
+                "req",
+                "-x509",
+                "-nodes",
+                "-new",
+                "-sha256",
+                "-days",
+                "3650",
+                "-newkey",
+                "rsa:2048",
+                "-keyout",
+                caKeyPath,
+                "-out",
+                caCertPath,
+                "-subj",
+                "/CN=HoverSourceRootCA",
+            ], { stdio: "ignore" });
+        }
+        catch (err) {
+            console.error(`[HoverSource SSL CA] Failed to generate Root CA:`, err.message);
+            throw new Error(`Failed to generate local Root CA keys. Please check openssl configuration.`);
+        }
+    }
+    // 2. Register Root CA to Windows Trusted Root store if not already done (Windows specific)
+    if (process.platform === "win32") {
+        try {
+            // Check if certificate is already trusted
+            execFileSync("certutil", ["-verifystore", "-user", "root", "HoverSourceRootCA"], { stdio: "ignore" });
+        }
+        catch {
+            try {
+                console.log(`[HoverSource SSL CA] Trusting HoverSource Development Root CA...`);
+                execFileSync("certutil", ["-addstore", "-user", "root", caCertPath], { stdio: "ignore" });
+            }
+            catch (err) {
+                console.warn(`[HoverSource SSL CA] Warning: Failed to trust Root CA in Windows certificate store:`, err.message);
+            }
+        }
+    }
+    return { caKeyPath, caCertPath };
+}
+/**
+ * Generates and signs a local domain SSL certificate for the specified target host
+ * using the HoverSource Root CA.
+ */
+export function getOrCreateCaSignedCert(targetHost) {
+    const { caKeyPath, caCertPath } = ensureRootCa();
+    const tempDir = os.tmpdir();
+    const openssl = getOpensslCommand();
+    // Clean host name for filenames
+    const safeHost = targetHost.replace(/[^a-zA-Z0-9.-]/g, "_");
+    const domainKeyPath = path.join(tempDir, `hoversource-signed-${safeHost}.key`);
+    const domainCertPath = path.join(tempDir, `hoversource-signed-${safeHost}.crt`);
+    const domainCsrPath = path.join(tempDir, `hoversource-signed-${safeHost}.csr`);
+    const extConfigPath = path.join(tempDir, `hoversource-ext-${safeHost}.conf`);
+    // Check if it already exists and is relatively new (less than 30 days old)
+    if (fs.existsSync(domainKeyPath) && fs.existsSync(domainCertPath)) {
+        const keyStat = fs.statSync(domainKeyPath);
+        const ageInHours = (Date.now() - keyStat.mtimeMs) / (1000 * 60 * 60);
+        if (ageInHours < 24 * 30) {
+            return {
+                key: fs.readFileSync(domainKeyPath, "utf-8"),
+                cert: fs.readFileSync(domainCertPath, "utf-8"),
+            };
+        }
+    }
+    try {
+        // Generate extension config containing SAN (Subject Alternative Names)
+        const dnsNames = ["localhost", "127.0.0.1"];
+        if (targetHost && targetHost !== "localhost" && targetHost !== "127.0.0.1") {
+            dnsNames.push(targetHost);
+        }
+        const altNames = dnsNames.map((name, index) => {
+            const isIp = /^[0-9.]+$/.test(name);
+            return `${isIp ? "IP" : "DNS"}.${index + 1} = ${name}`;
+        }).join("\n");
+        const extConfig = `authorityKeyIdentifier=keyid,issuer
+basicConstraints=CA:FALSE
+keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
+subjectAltName = @alt_names
+
+[alt_names]
+${altNames}
+`;
+        fs.writeFileSync(extConfigPath, extConfig.replaceAll("\r\n", "\n"), "utf-8");
+        // Generate Private Key and CSR for Domain
+        execFileSync(openssl, [
+            "req",
+            "-new",
+            "-newkey",
+            "rsa:2048",
+            "-nodes",
+            "-keyout",
+            domainKeyPath,
+            "-out",
+            domainCsrPath,
+            "-subj",
+            `/CN=${targetHost}`,
+        ], { stdio: "pipe" });
+        // Sign CSR with Root CA using Extension config
+        execFileSync(openssl, [
+            "x509",
+            "-req",
+            "-in",
+            domainCsrPath,
+            "-CA",
+            caCertPath,
+            "-CAkey",
+            caKeyPath,
+            "-CAcreateserial",
+            "-out",
+            domainCertPath,
+            "-days",
+            "365",
+            "-sha256",
+            "-extfile",
+            extConfigPath,
+        ], { stdio: "pipe" });
+        // Clean up temporary config and CSR
+        try {
+            fs.unlinkSync(extConfigPath);
+            fs.unlinkSync(domainCsrPath);
+            const serialPath = path.join(tempDir, `hoversource-signed-${safeHost}.srl`);
+            if (fs.existsSync(serialPath))
+                fs.unlinkSync(serialPath);
+            const localSerialPath = "ca.srl"; // Openssl sometimes places CA serial file in cwd
+            if (fs.existsSync(localSerialPath))
+                fs.unlinkSync(localSerialPath);
+        }
+        catch { }
+        return {
+            key: fs.readFileSync(domainKeyPath, "utf-8"),
+            cert: fs.readFileSync(domainCertPath, "utf-8"),
+        };
+    }
+    catch (err) {
+        const stderrStr = err.stderr ? ` Stderr: ${err.stderr.toString()}` : "";
+        console.error(`[HoverSource SSL CA] Failed to generate signed certificate for ${targetHost}:`, err.message + stderrStr);
+        throw new Error(`OpenSSL signed cert generation failed: ${err.message}${stderrStr}`);
+    }
+}

package/dist/cert.d.ts

@@ -0,0 +1,15 @@
+export interface SslCertConfig {
+    keyPath?: string;
+    certPath?: string;
+    targetHost?: string;
+}
+export interface SslCredentials {
+    key: string;
+    cert: string;
+}
+/**
+ * Returns SSL credentials for local HTTPS development.
+ * If user-defined key and cert paths are provided and exist, they are loaded.
+ * Otherwise, generates a self-signed SSL certificate for localhost dynamically in the temp folder.
+ */
+export declare function getOrCreateLocalSslCert(config?: SslCertConfig): SslCredentials;

package/dist/cert.js

@@ -0,0 +1,76 @@
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+import { getOrCreateCaSignedCert, getOpensslCommand } from "./cert-ca.js";
+/**
+ * Returns SSL credentials for local HTTPS development.
+ * If user-defined key and cert paths are provided and exist, they are loaded.
+ * Otherwise, generates a self-signed SSL certificate for localhost dynamically in the temp folder.
+ */
+export function getOrCreateLocalSslCert(config = {}) {
+    if (config.keyPath && config.certPath) {
+        const keyAbsPath = path.resolve(config.keyPath);
+        const certAbsPath = path.resolve(config.certPath);
+        if (fs.existsSync(keyAbsPath) && fs.existsSync(certAbsPath)) {
+            return {
+                key: fs.readFileSync(keyAbsPath, "utf-8"),
+                cert: fs.readFileSync(certAbsPath, "utf-8"),
+            };
+        }
+        console.warn(`[HoverSource SSL] Provided certificate files not found: ${keyAbsPath} or ${certAbsPath}. Falling back to self-signed generator.`);
+    }
+    if (config.targetHost) {
+        try {
+            return getOrCreateCaSignedCert(config.targetHost);
+        }
+        catch (err) {
+            console.warn(`[HoverSource SSL] Failed to generate CA-signed cert for ${config.targetHost}. Falling back to default self-signed cert. Error: ${err.message}`);
+        }
+    }
+    // Fallback: Generate self-signed certificate in the OS temp directory
+    const tempDir = os.tmpdir();
+    const keyPath = path.join(tempDir, "hoversource-selfsigned-localhost.key");
+    const certPath = path.join(tempDir, "hoversource-selfsigned-localhost.crt");
+    // Re-use already generated certs in temp if they exist to avoid openssl cost on every startup
+    if (fs.existsSync(keyPath) && fs.existsSync(certPath)) {
+        const keyStat = fs.statSync(keyPath);
+        const ageInHours = (Date.now() - keyStat.mtimeMs) / (1000 * 60 * 60);
+        // Regenerate if older than 30 days
+        if (ageInHours < 24 * 30) {
+            return {
+                key: fs.readFileSync(keyPath, "utf-8"),
+                cert: fs.readFileSync(certPath, "utf-8"),
+            };
+        }
+    }
+    try {
+        console.log(`[HoverSource SSL] Generating self-signed SSL certificate for localhost...`);
+        // Run openssl command cross-platform.
+        const openssl = getOpensslCommand();
+        execFileSync(openssl, [
+            "req",
+            "-x509",
+            "-newkey",
+            "rsa:2048",
+            "-nodes",
+            "-sha256",
+            "-subj",
+            "/CN=localhost",
+            "-keyout",
+            keyPath,
+            "-out",
+            certPath,
+            "-days",
+            "365",
+        ], { stdio: "ignore" });
+        return {
+            key: fs.readFileSync(keyPath, "utf-8"),
+            cert: fs.readFileSync(certPath, "utf-8"),
+        };
+    }
+    catch (err) {
+        console.error(`[HoverSource SSL] Failed to generate self-signed certificate using 'openssl'. Make sure openssl is installed. Error: ${err.message}`);
+        throw new Error(`[HoverSource SSL] OpenSSL execution failed. Cannot start HTTPS proxy without valid certificates.`);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+export { isPortFree, findFreePort, getPidUsingPort, getProcessName, killProcess, askQuestion, isZombieOfProject, resolveCompanionPort, resolveDevServerPort, resolveAllPorts } from "./port.js";
+export type { DevServerPortResult, PortPlan } from "./port.js";
+export declare function validateSafePath(p: string): string;
+export declare function validateSafeCommand(cmd: string): string;
+export declare function validateSafeUrl(urlStr: string): string;
+export declare function detectDevServerPort(projectRoot: string, execCommand?: string): number;
+export declare function resolveDebugPortConflicts(debugPort: number, projectRoot: string, autoResolve: boolean, args: any): Promise<{
+    resolvedDebugPort: number;
+    patchRestorer?: () => void;
+}>;
+export declare function runProxyMode(targetUrl: string, serverPort: number, args: any): Promise<void>;
+export declare function waitForServer(port: number, timeoutMs?: number, hasExitedCheck?: () => boolean): Promise<boolean>;
+export declare function cleanArgument(arg: string): string;
+export declare function parseCommand(cmdString: string): {
+    command: string;
+    args: string[];
+};
+export declare function resolveWindowsCommand(command: string): string;
+export declare function findScriptPath(projectRoot: string): string;
+export declare function startCdpInjectionWatch(debugPort: number, scriptWithPort: string): Promise<void>;
+export declare function handleExecMode(execArg: string, subcommand: string | undefined, projectRoot: string, debugPort: number, serverPort: number, args: Record<string, string | boolean>): Promise<void>;