@quilltap/plugin-utils 1.2.5 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to @quilltap/plugin-utils will be documented in this file.
 
+## [1.4.0] - 2026-02-25
+
+### Added
+
+- **Host URL Rewriting Utilities**
+  - `isVMEnvironment()` - Check if running in a VM/container environment (Docker, Lima, WSL2)
+  - `resolveHostGateway()` - Resolve the host gateway address with multi-strategy fallback
+  - `rewriteLocalhostUrl()` - Transparently rewrite localhost URLs to point at the host gateway
+  - Self-contained environment detection (no dependency on Quilltap core `lib/paths`)
+  - Uses `createPluginLogger` for consistent logging within the plugin ecosystem
+  - New export path: `@quilltap/plugin-utils/host-rewrite`
+
+## [1.3.0] - 2026-01-30
+
+### Added
+
+- **Built-in Tool Names for Collision Detection**
+  - Added `BUILTIN_TOOL_NAMES` constant with names of Quilltap's built-in tools
+  - Added `getBuiltinToolNames()` function for dynamic access to the set
+  - Enables plugins (like MCP connectors) to avoid shadowing built-in functionality
+  - Built-in tools: `generate_image`, `search_memories`, `search_web`, `project_info`, `file_management`, `request_full_context`
+
 ## [1.2.5] - 2026-01-25
 
 ### Fixed

package/dist/host-rewrite.d.mts

@@ -0,0 +1,52 @@
+/**
+ * Host URL Rewriting for VM/Container Environments
+ *
+ * When Quilltap runs inside Docker, Lima VMs, or WSL2, `localhost` and
+ * `127.0.0.1` resolve to the container/VM's own loopback — not the host
+ * machine where services like Ollama or LM Studio are running.
+ *
+ * This module provides a single function that transparently rewrites
+ * localhost URLs to point at the host, so users can configure
+ * `http://localhost:11434` and have it Just Work in every environment.
+ *
+ * Gateway resolution order:
+ * 1. `QUILLTAP_HOST_IP` env var (explicit override) → rewrite to that IP
+ * 2. In Docker (not Lima): rewrite `localhost` → `host.docker.internal`
+ *    (Docker Desktop DNS or --add-host on Linux handles the forwarding)
+ * 3. Default gateway from /proc/net/route (works in Lima and WSL2 where
+ *    NAT networking forwards to host loopback)
+ * 4. Fallback: try DNS lookup of `host.docker.internal` via /etc/hosts
+ * 5. Give up gracefully — return URL unchanged
+ *
+ * @module @quilltap/plugin-utils/host-rewrite
+ */
+/**
+ * Check if running in any VM or container environment that needs URL rewriting.
+ */
+declare function isVMEnvironment(): boolean;
+/**
+ * Resolve the host gateway address (IP or hostname).
+ *
+ * Tries multiple strategies in order; caches the result so file reads
+ * only happen once per process lifetime.
+ */
+declare function resolveHostGateway(): string | null;
+/**
+ * Rewrite a localhost URL to point at the host gateway.
+ *
+ * No-ops when:
+ * - Not running in a VM/container environment
+ * - The URL doesn't point to localhost or 127.0.0.1
+ * - Gateway resolution fails
+ *
+ * @param url The URL to potentially rewrite
+ * @returns The original URL or a rewritten version with the gateway host
+ */
+declare function rewriteLocalhostUrl(url: string): string;
+/**
+ * Reset the cached gateway host (for testing).
+ * @internal
+ */
+declare function _resetGatewayCache(): void;
+
+export { _resetGatewayCache, isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl };

package/dist/host-rewrite.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Host URL Rewriting for VM/Container Environments
+ *
+ * When Quilltap runs inside Docker, Lima VMs, or WSL2, `localhost` and
+ * `127.0.0.1` resolve to the container/VM's own loopback — not the host
+ * machine where services like Ollama or LM Studio are running.
+ *
+ * This module provides a single function that transparently rewrites
+ * localhost URLs to point at the host, so users can configure
+ * `http://localhost:11434` and have it Just Work in every environment.
+ *
+ * Gateway resolution order:
+ * 1. `QUILLTAP_HOST_IP` env var (explicit override) → rewrite to that IP
+ * 2. In Docker (not Lima): rewrite `localhost` → `host.docker.internal`
+ *    (Docker Desktop DNS or --add-host on Linux handles the forwarding)
+ * 3. Default gateway from /proc/net/route (works in Lima and WSL2 where
+ *    NAT networking forwards to host loopback)
+ * 4. Fallback: try DNS lookup of `host.docker.internal` via /etc/hosts
+ * 5. Give up gracefully — return URL unchanged
+ *
+ * @module @quilltap/plugin-utils/host-rewrite
+ */
+/**
+ * Check if running in any VM or container environment that needs URL rewriting.
+ */
+declare function isVMEnvironment(): boolean;
+/**
+ * Resolve the host gateway address (IP or hostname).
+ *
+ * Tries multiple strategies in order; caches the result so file reads
+ * only happen once per process lifetime.
+ */
+declare function resolveHostGateway(): string | null;
+/**
+ * Rewrite a localhost URL to point at the host gateway.
+ *
+ * No-ops when:
+ * - Not running in a VM/container environment
+ * - The URL doesn't point to localhost or 127.0.0.1
+ * - Gateway resolution fails
+ *
+ * @param url The URL to potentially rewrite
+ * @returns The original URL or a rewritten version with the gateway host
+ */
+declare function rewriteLocalhostUrl(url: string): string;
+/**
+ * Reset the cached gateway host (for testing).
+ * @internal
+ */
+declare function _resetGatewayCache(): void;
+
+export { _resetGatewayCache, isVMEnvironment, resolveHostGateway, rewriteLocalhostUrl };

package/dist/host-rewrite.js

@@ -0,0 +1,210 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/host-rewrite.ts
+var host_rewrite_exports = {};
+__export(host_rewrite_exports, {
+  _resetGatewayCache: () => _resetGatewayCache,
+  isVMEnvironment: () => isVMEnvironment,
+  resolveHostGateway: () => resolveHostGateway,
+  rewriteLocalhostUrl: () => rewriteLocalhostUrl
+});
+module.exports = __toCommonJS(host_rewrite_exports);
+
+// src/logging/plugin-logger.ts
+function getCoreLoggerFactory() {
+  return globalThis.__quilltap_logger_factory ?? null;
+}
+function createConsoleLoggerWithChild(prefix, minLevel = "debug", baseContext = {}) {
+  const levels = ["debug", "info", "warn", "error"];
+  const shouldLog = (level) => levels.indexOf(level) >= levels.indexOf(minLevel);
+  const formatContext = (context) => {
+    const merged = { ...baseContext, ...context };
+    const entries = Object.entries(merged).filter(([key]) => key !== "context").map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+    return entries ? ` ${entries}` : "";
+  };
+  const logger = {
+    debug: (message, context) => {
+      if (shouldLog("debug")) {
+        console.debug(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    info: (message, context) => {
+      if (shouldLog("info")) {
+        console.info(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    warn: (message, context) => {
+      if (shouldLog("warn")) {
+        console.warn(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    error: (message, context, error) => {
+      if (shouldLog("error")) {
+        console.error(
+          `[${prefix}] ${message}${formatContext(context)}`,
+          error ? `
+${error.stack || error.message}` : ""
+        );
+      }
+    },
+    child: (additionalContext) => {
+      return createConsoleLoggerWithChild(prefix, minLevel, {
+        ...baseContext,
+        ...additionalContext
+      });
+    }
+  };
+  return logger;
+}
+function createPluginLogger(pluginName, minLevel = "debug") {
+  const coreFactory = getCoreLoggerFactory();
+  if (coreFactory) {
+    return coreFactory(pluginName);
+  }
+  return createConsoleLoggerWithChild(pluginName, minLevel);
+}
+
+// src/logging/index.ts
+var import_plugin_types = require("@quilltap/plugin-types");
+
+// src/host-rewrite.ts
+var import_node_fs = require("fs");
+var LOCALHOST_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "[::1]",
+  "::1"
+]);
+var cachedGatewayHost;
+var rewriteLogger = createPluginLogger("host-rewrite");
+function isLimaEnvironment() {
+  return process.env.LIMA_CONTAINER === "true";
+}
+function isDockerEnvironment() {
+  if (process.env.DOCKER_CONTAINER === "true") {
+    return true;
+  }
+  try {
+    if ((0, import_node_fs.existsSync)("/.dockerenv")) {
+      return true;
+    }
+    const appStat = (0, import_node_fs.statSync)("/app");
+    if (appStat.isDirectory()) {
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function isVMEnvironment() {
+  return isDockerEnvironment() || isLimaEnvironment();
+}
+function resolveHostGateway() {
+  if (cachedGatewayHost !== void 0) {
+    return cachedGatewayHost;
+  }
+  const envIP = process.env.QUILLTAP_HOST_IP;
+  if (envIP) {
+    rewriteLogger.info("Host gateway from QUILLTAP_HOST_IP", { host: envIP });
+    cachedGatewayHost = envIP;
+    return cachedGatewayHost;
+  }
+  if (isDockerEnvironment() && !isLimaEnvironment()) {
+    rewriteLogger.info("Docker environment detected \u2014 using host.docker.internal as gateway hostname");
+    cachedGatewayHost = "host.docker.internal";
+    return cachedGatewayHost;
+  }
+  try {
+    const routeTable = (0, import_node_fs.readFileSync)("/proc/net/route", "utf-8");
+    for (const line of routeTable.split("\n").slice(1)) {
+      const fields = line.trim().split("	");
+      if (fields.length >= 3 && fields[1] === "00000000") {
+        const hexGateway = fields[2];
+        const ip = [
+          parseInt(hexGateway.substring(6, 8), 16),
+          parseInt(hexGateway.substring(4, 6), 16),
+          parseInt(hexGateway.substring(2, 4), 16),
+          parseInt(hexGateway.substring(0, 2), 16)
+        ].join(".");
+        rewriteLogger.info("Host gateway IP from /proc/net/route", { ip });
+        cachedGatewayHost = ip;
+        return cachedGatewayHost;
+      }
+    }
+  } catch {
+    rewriteLogger.debug("Could not read /proc/net/route for default gateway lookup");
+  }
+  try {
+    const hosts = (0, import_node_fs.readFileSync)("/etc/hosts", "utf-8");
+    for (const line of hosts.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || trimmed === "") continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts.length >= 2 && parts.slice(1).includes("host.docker.internal")) {
+        const ip = parts[0];
+        rewriteLogger.info("Host gateway IP from /etc/hosts (host.docker.internal)", { ip });
+        cachedGatewayHost = ip;
+        return cachedGatewayHost;
+      }
+    }
+  } catch {
+    rewriteLogger.debug("Could not read /etc/hosts for host.docker.internal lookup");
+  }
+  rewriteLogger.warn("Could not resolve host gateway \u2014 localhost URLs will not be rewritten");
+  cachedGatewayHost = null;
+  return cachedGatewayHost;
+}
+function rewriteLocalhostUrl(url) {
+  if (!isVMEnvironment()) {
+    return url;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+  if (!LOCALHOST_HOSTS.has(parsed.hostname)) {
+    return url;
+  }
+  const gatewayHost = resolveHostGateway();
+  if (!gatewayHost) {
+    return url;
+  }
+  parsed.hostname = gatewayHost;
+  const rewritten = parsed.toString();
+  rewriteLogger.debug("Rewrote localhost URL", {
+    original: url,
+    rewritten,
+    gatewayHost
+  });
+  return rewritten;
+}
+function _resetGatewayCache() {
+  cachedGatewayHost = void 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  _resetGatewayCache,
+  isVMEnvironment,
+  resolveHostGateway,
+  rewriteLocalhostUrl
+});
+//# sourceMappingURL=host-rewrite.js.map

package/dist/host-rewrite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/host-rewrite.ts","../src/logging/plugin-logger.ts","../src/logging/index.ts"],"sourcesContent":["/**\n * Host URL Rewriting for VM/Container Environments\n *\n * When Quilltap runs inside Docker, Lima VMs, or WSL2, `localhost` and\n * `127.0.0.1` resolve to the container/VM's own loopback — not the host\n * machine where services like Ollama or LM Studio are running.\n *\n * This module provides a single function that transparently rewrites\n * localhost URLs to point at the host, so users can configure\n * `http://localhost:11434` and have it Just Work in every environment.\n *\n * Gateway resolution order:\n * 1. `QUILLTAP_HOST_IP` env var (explicit override) → rewrite to that IP\n * 2. In Docker (not Lima): rewrite `localhost` → `host.docker.internal`\n *    (Docker Desktop DNS or --add-host on Linux handles the forwarding)\n * 3. Default gateway from /proc/net/route (works in Lima and WSL2 where\n *    NAT networking forwards to host loopback)\n * 4. Fallback: try DNS lookup of `host.docker.internal` via /etc/hosts\n * 5. Give up gracefully — return URL unchanged\n *\n * @module @quilltap/plugin-utils/host-rewrite\n */\n\nimport { createPluginLogger } from './logging';\nimport { readFileSync, existsSync, statSync } from 'node:fs';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Hostnames that refer to the local loopback */\nconst LOCALHOST_HOSTS = new Set([\n  'localhost',\n  '127.0.0.1',\n  '[::1]',\n  '::1',\n]);\n\n// ============================================================================\n// Cached Gateway Host\n// ============================================================================\n\nlet cachedGatewayHost: string | null | undefined; // undefined = not yet resolved\n\nconst rewriteLogger = createPluginLogger('host-rewrite');\n\n// ============================================================================\n// Environment Detection (self-contained)\n// ============================================================================\n\n/**\n * Check if running inside a Lima VM.\n *\n * Lima VMs are provisioned with LIMA_CONTAINER=true in /etc/profile.d/quilltap.sh.\n */\nfunction isLimaEnvironment(): boolean {\n  return process.env.LIMA_CONTAINER === 'true';\n}\n\n/**\n * Check if running in a Docker container.\n *\n * Detects Docker by checking:\n * 1. DOCKER_CONTAINER environment variable\n * 2. Existence of /.dockerenv file\n * 3. Existence of /app directory (Quilltap Docker convention)\n */\nfunction isDockerEnvironment(): boolean {\n  if (process.env.DOCKER_CONTAINER === 'true') {\n    return true;\n  }\n\n  // Check for Docker-specific markers\n  try {\n    if (existsSync('/.dockerenv')) {\n      return true;\n    }\n    // Check for /app as a directory (Quilltap Docker convention)\n    const appStat = statSync('/app');\n    if (appStat.isDirectory()) {\n      return true;\n    }\n  } catch {\n    // Not in Docker\n  }\n\n  return false;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Check if running in any VM or container environment that needs URL rewriting.\n */\nexport function isVMEnvironment(): boolean {\n  return isDockerEnvironment() || isLimaEnvironment();\n}\n\n/**\n * Resolve the host gateway address (IP or hostname).\n *\n * Tries multiple strategies in order; caches the result so file reads\n * only happen once per process lifetime.\n */\nexport function resolveHostGateway(): string | null {\n  // Return cached result if already resolved\n  if (cachedGatewayHost !== undefined) {\n    return cachedGatewayHost;\n  }\n\n  // Strategy 1: Explicit env var override\n  const envIP = process.env.QUILLTAP_HOST_IP;\n  if (envIP) {\n    rewriteLogger.info('Host gateway from QUILLTAP_HOST_IP', { host: envIP });\n    cachedGatewayHost = envIP;\n    return cachedGatewayHost;\n  }\n\n  // Strategy 2: Docker — use host.docker.internal directly as a hostname\n  // Docker Desktop (macOS/Windows) provides built-in DNS resolution for\n  // host.docker.internal via its DNS server (127.0.0.11).  Linux Docker\n  // needs --add-host=host.docker.internal:host-gateway (handled by the\n  // start scripts).  Either way, host.docker.internal correctly forwards\n  // to services bound to the host's loopback (127.0.0.1).\n  //\n  // This MUST run before /proc/net/route for Docker because the bridge\n  // gateway IP returned by /proc/net/route (e.g. 172.17.0.1) is just\n  // the Docker bridge interface — services listening on the host's\n  // localhost are NOT reachable through it.\n  //\n  // Lima VMs are excluded here: they trigger isDockerEnvironment() (they\n  // have /app) but don't have host.docker.internal in DNS.  Lima uses\n  // VZ NAT networking where the /proc/net/route gateway genuinely\n  // forwards to the host loopback.\n  if (isDockerEnvironment() && !isLimaEnvironment()) {\n    rewriteLogger.info('Docker environment detected — using host.docker.internal as gateway hostname');\n    cachedGatewayHost = 'host.docker.internal';\n    return cachedGatewayHost;\n  }\n\n  // Strategy 3: Default gateway from /proc/net/route (Lima/WSL2)\n  // Parse the kernel routing table directly instead of shelling out to\n  // `ip route`, which is unavailable in Alpine Linux images.\n  // The file format is tab-separated with hex-encoded IPs.\n  // This works for Lima and WSL2 where NAT networking forwards traffic\n  // from the gateway IP to the host's loopback.\n  try {\n    const routeTable = readFileSync('/proc/net/route', 'utf-8');\n    for (const line of routeTable.split('\\n').slice(1)) { // skip header\n      const fields = line.trim().split('\\t');\n      // fields[1] = Destination, fields[2] = Gateway\n      // Default route has destination 00000000\n      if (fields.length >= 3 && fields[1] === '00000000') {\n        const hexGateway = fields[2];\n        // Convert hex gateway to dotted-quad IP (little-endian on Linux)\n        const ip = [\n          parseInt(hexGateway.substring(6, 8), 16),\n          parseInt(hexGateway.substring(4, 6), 16),\n          parseInt(hexGateway.substring(2, 4), 16),\n          parseInt(hexGateway.substring(0, 2), 16),\n        ].join('.');\n        rewriteLogger.info('Host gateway IP from /proc/net/route', { ip });\n        cachedGatewayHost = ip;\n        return cachedGatewayHost;\n      }\n    }\n  } catch {\n    rewriteLogger.debug('Could not read /proc/net/route for default gateway lookup');\n  }\n\n  // Strategy 4: Fallback — resolve host.docker.internal from /etc/hosts\n  // Covers edge cases where Docker adds it to /etc/hosts but we're not\n  // detected as Docker (e.g., custom container runtimes).\n  try {\n    const hosts = readFileSync('/etc/hosts', 'utf-8');\n    for (const line of hosts.split('\\n')) {\n      const trimmed = line.trim();\n      if (trimmed.startsWith('#') || trimmed === '') continue;\n      // /etc/hosts format: <IP> <hostname1> [hostname2] ...\n      const parts = trimmed.split(/\\s+/);\n      if (parts.length >= 2 && parts.slice(1).includes('host.docker.internal')) {\n        const ip = parts[0];\n        rewriteLogger.info('Host gateway IP from /etc/hosts (host.docker.internal)', { ip });\n        cachedGatewayHost = ip;\n        return cachedGatewayHost;\n      }\n    }\n  } catch {\n    rewriteLogger.debug('Could not read /etc/hosts for host.docker.internal lookup');\n  }\n\n  rewriteLogger.warn('Could not resolve host gateway — localhost URLs will not be rewritten');\n  cachedGatewayHost = null;\n  return cachedGatewayHost;\n}\n\n/**\n * Rewrite a localhost URL to point at the host gateway.\n *\n * No-ops when:\n * - Not running in a VM/container environment\n * - The URL doesn't point to localhost or 127.0.0.1\n * - Gateway resolution fails\n *\n * @param url The URL to potentially rewrite\n * @returns The original URL or a rewritten version with the gateway host\n */\nexport function rewriteLocalhostUrl(url: string): string {\n  // No-op on bare metal\n  if (!isVMEnvironment()) {\n    return url;\n  }\n\n  // Parse the URL to check the hostname\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    // Not a valid URL — return unchanged\n    return url;\n  }\n\n  // Check if hostname is a localhost variant\n  if (!LOCALHOST_HOSTS.has(parsed.hostname)) {\n    return url;\n  }\n\n  // Resolve the gateway host\n  const gatewayHost = resolveHostGateway();\n  if (!gatewayHost) {\n    return url;\n  }\n\n  // Rewrite the hostname\n  parsed.hostname = gatewayHost;\n  const rewritten = parsed.toString();\n\n  rewriteLogger.debug('Rewrote localhost URL', {\n    original: url,\n    rewritten,\n    gatewayHost,\n  });\n\n  return rewritten;\n}\n\n/**\n * Reset the cached gateway host (for testing).\n * @internal\n */\nexport function _resetGatewayCache(): void {\n  cachedGatewayHost = undefined;\n}\n","/**\n * Plugin Logger Bridge\n *\n * Provides a logger factory for plugins that automatically bridges\n * to Quilltap's core logging when running inside the host application,\n * or falls back to console logging when running standalone.\n *\n * @module @quilltap/plugin-utils/logging/plugin-logger\n */\n\nimport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n/**\n * Extended logger interface with child logger support\n */\nexport interface PluginLoggerWithChild extends PluginLogger {\n  /**\n   * Create a child logger with additional context\n   * @param additionalContext Context to merge with parent context\n   * @returns A new logger with combined context\n   */\n  child(additionalContext: LogContext): PluginLoggerWithChild;\n}\n\n/**\n * Type for the global Quilltap logger bridge\n * Stored on globalThis to work across different npm package copies\n */\ndeclare global {\n   \n  var __quilltap_logger_factory:\n    | ((pluginName: string) => PluginLoggerWithChild)\n    | undefined;\n}\n\n/**\n * Get the core logger factory from global namespace\n *\n * @returns The injected factory or null if not in Quilltap environment\n */\nfunction getCoreLoggerFactory(): ((pluginName: string) => PluginLoggerWithChild) | null {\n  return globalThis.__quilltap_logger_factory ?? null;\n}\n\n/**\n * Inject the core logger factory from Quilltap host\n *\n * This is called by Quilltap core when loading plugins to bridge\n * plugin logging into the host's logging system. Uses globalThis\n * to ensure it works even when plugins have their own copy of\n * plugin-utils in their node_modules.\n *\n * **Internal API - not for plugin use**\n *\n * @param factory A function that creates a child logger for a plugin\n */\nexport function __injectCoreLoggerFactory(\n  factory: (pluginName: string) => PluginLoggerWithChild\n): void {\n  globalThis.__quilltap_logger_factory = factory;\n}\n\n/**\n * Clear the injected core logger factory\n *\n * Useful for testing or when unloading the plugin system.\n *\n * **Internal API - not for plugin use**\n */\nexport function __clearCoreLoggerFactory(): void {\n  globalThis.__quilltap_logger_factory = undefined;\n}\n\n/**\n * Check if a core logger has been injected\n *\n * @returns True if running inside Quilltap with core logging available\n */\nexport function hasCoreLogger(): boolean {\n  return getCoreLoggerFactory() !== null;\n}\n\n/**\n * Create a console logger with child support\n *\n * @param prefix Logger prefix\n * @param minLevel Minimum log level\n * @param baseContext Base context to include in all logs\n */\nfunction createConsoleLoggerWithChild(\n  prefix: string,\n  minLevel: LogLevel = 'debug',\n  baseContext: LogContext = {}\n): PluginLoggerWithChild {\n  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];\n  const shouldLog = (level: LogLevel): boolean =>\n    levels.indexOf(level) >= levels.indexOf(minLevel);\n\n  const formatContext = (context?: LogContext): string => {\n    const merged = { ...baseContext, ...context };\n    const entries = Object.entries(merged)\n      .filter(([key]) => key !== 'context')\n      .map(([key, value]) => `${key}=${JSON.stringify(value)}`)\n      .join(' ');\n    return entries ? ` ${entries}` : '';\n  };\n\n  const logger: PluginLoggerWithChild = {\n    debug: (message: string, context?: LogContext): void => {\n      if (shouldLog('debug')) {\n        console.debug(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    info: (message: string, context?: LogContext): void => {\n      if (shouldLog('info')) {\n        console.info(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    warn: (message: string, context?: LogContext): void => {\n      if (shouldLog('warn')) {\n        console.warn(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    error: (message: string, context?: LogContext, error?: Error): void => {\n      if (shouldLog('error')) {\n        console.error(\n          `[${prefix}] ${message}${formatContext(context)}`,\n          error ? `\\n${error.stack || error.message}` : ''\n        );\n      }\n    },\n\n    child: (additionalContext: LogContext): PluginLoggerWithChild => {\n      return createConsoleLoggerWithChild(prefix, minLevel, {\n        ...baseContext,\n        ...additionalContext,\n      });\n    },\n  };\n\n  return logger;\n}\n\n/**\n * Create a plugin logger that bridges to Quilltap core logging\n *\n * When running inside Quilltap:\n * - Routes all logs to the core logger\n * - Tags logs with `{ plugin: pluginName, module: 'plugin' }`\n * - Logs appear in Quilltap's combined.log and console\n *\n * When running standalone:\n * - Falls back to console logging with `[pluginName]` prefix\n * - Respects the specified minimum log level\n *\n * @param pluginName - The plugin identifier (e.g., 'qtap-plugin-openai')\n * @param minLevel - Minimum log level when running standalone (default: 'debug')\n * @returns A logger instance\n *\n * @example\n * ```typescript\n * // In your plugin's provider.ts\n * import { createPluginLogger } from '@quilltap/plugin-utils';\n *\n * const logger = createPluginLogger('qtap-plugin-my-provider');\n *\n * export class MyProvider implements LLMProvider {\n *   async sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse> {\n *     logger.debug('Sending message', { model: params.model });\n *\n *     try {\n *       const response = await this.client.chat({...});\n *       logger.info('Received response', { tokens: response.usage?.total_tokens });\n *       return response;\n *     } catch (error) {\n *       logger.error('Failed to send message', { model: params.model }, error as Error);\n *       throw error;\n *     }\n *   }\n * }\n * ```\n */\nexport function createPluginLogger(\n  pluginName: string,\n  minLevel: LogLevel = 'debug'\n): PluginLoggerWithChild {\n  // Check for core logger factory from global namespace\n  const coreFactory = getCoreLoggerFactory();\n  if (coreFactory) {\n    return coreFactory(pluginName);\n  }\n\n  // Standalone mode: use enhanced console logger\n  return createConsoleLoggerWithChild(pluginName, minLevel);\n}\n\n/**\n * Get the minimum log level from environment\n *\n * Checks for LOG_LEVEL or QUILLTAP_LOG_LEVEL environment variables.\n * Useful for configuring standalone plugin logging.\n *\n * @returns The configured log level, or 'info' as default\n */\nexport function getLogLevelFromEnv(): LogLevel {\n  if (typeof process !== 'undefined' && process.env) {\n    const envLevel = process.env.LOG_LEVEL || process.env.QUILLTAP_LOG_LEVEL;\n    if (envLevel && ['debug', 'info', 'warn', 'error'].includes(envLevel)) {\n      return envLevel as LogLevel;\n    }\n  }\n  return 'info';\n}\n","/**\n * Logging Utilities\n *\n * Exports the plugin logger bridge and related utilities.\n *\n * @module @quilltap/plugin-utils/logging\n */\n\nexport {\n  createPluginLogger,\n  hasCoreLogger,\n  getLogLevelFromEnv,\n  __injectCoreLoggerFactory,\n  __clearCoreLoggerFactory,\n} from './plugin-logger';\n\nexport type { PluginLoggerWithChild } from './plugin-logger';\n\n// Re-export logger types from plugin-types\nexport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n// Re-export logger utilities from plugin-types for convenience\nexport { createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';\n"],"mappings":"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","names":[]}

package/dist/host-rewrite.mjs

@@ -0,0 +1,180 @@
+// src/logging/plugin-logger.ts
+function getCoreLoggerFactory() {
+  return globalThis.__quilltap_logger_factory ?? null;
+}
+function createConsoleLoggerWithChild(prefix, minLevel = "debug", baseContext = {}) {
+  const levels = ["debug", "info", "warn", "error"];
+  const shouldLog = (level) => levels.indexOf(level) >= levels.indexOf(minLevel);
+  const formatContext = (context) => {
+    const merged = { ...baseContext, ...context };
+    const entries = Object.entries(merged).filter(([key]) => key !== "context").map(([key, value]) => `${key}=${JSON.stringify(value)}`).join(" ");
+    return entries ? ` ${entries}` : "";
+  };
+  const logger = {
+    debug: (message, context) => {
+      if (shouldLog("debug")) {
+        console.debug(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    info: (message, context) => {
+      if (shouldLog("info")) {
+        console.info(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    warn: (message, context) => {
+      if (shouldLog("warn")) {
+        console.warn(`[${prefix}] ${message}${formatContext(context)}`);
+      }
+    },
+    error: (message, context, error) => {
+      if (shouldLog("error")) {
+        console.error(
+          `[${prefix}] ${message}${formatContext(context)}`,
+          error ? `
+${error.stack || error.message}` : ""
+        );
+      }
+    },
+    child: (additionalContext) => {
+      return createConsoleLoggerWithChild(prefix, minLevel, {
+        ...baseContext,
+        ...additionalContext
+      });
+    }
+  };
+  return logger;
+}
+function createPluginLogger(pluginName, minLevel = "debug") {
+  const coreFactory = getCoreLoggerFactory();
+  if (coreFactory) {
+    return coreFactory(pluginName);
+  }
+  return createConsoleLoggerWithChild(pluginName, minLevel);
+}
+
+// src/logging/index.ts
+import { createConsoleLogger, createNoopLogger } from "@quilltap/plugin-types";
+
+// src/host-rewrite.ts
+import { readFileSync, existsSync, statSync } from "fs";
+var LOCALHOST_HOSTS = /* @__PURE__ */ new Set([
+  "localhost",
+  "127.0.0.1",
+  "[::1]",
+  "::1"
+]);
+var cachedGatewayHost;
+var rewriteLogger = createPluginLogger("host-rewrite");
+function isLimaEnvironment() {
+  return process.env.LIMA_CONTAINER === "true";
+}
+function isDockerEnvironment() {
+  if (process.env.DOCKER_CONTAINER === "true") {
+    return true;
+  }
+  try {
+    if (existsSync("/.dockerenv")) {
+      return true;
+    }
+    const appStat = statSync("/app");
+    if (appStat.isDirectory()) {
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function isVMEnvironment() {
+  return isDockerEnvironment() || isLimaEnvironment();
+}
+function resolveHostGateway() {
+  if (cachedGatewayHost !== void 0) {
+    return cachedGatewayHost;
+  }
+  const envIP = process.env.QUILLTAP_HOST_IP;
+  if (envIP) {
+    rewriteLogger.info("Host gateway from QUILLTAP_HOST_IP", { host: envIP });
+    cachedGatewayHost = envIP;
+    return cachedGatewayHost;
+  }
+  if (isDockerEnvironment() && !isLimaEnvironment()) {
+    rewriteLogger.info("Docker environment detected \u2014 using host.docker.internal as gateway hostname");
+    cachedGatewayHost = "host.docker.internal";
+    return cachedGatewayHost;
+  }
+  try {
+    const routeTable = readFileSync("/proc/net/route", "utf-8");
+    for (const line of routeTable.split("\n").slice(1)) {
+      const fields = line.trim().split("	");
+      if (fields.length >= 3 && fields[1] === "00000000") {
+        const hexGateway = fields[2];
+        const ip = [
+          parseInt(hexGateway.substring(6, 8), 16),
+          parseInt(hexGateway.substring(4, 6), 16),
+          parseInt(hexGateway.substring(2, 4), 16),
+          parseInt(hexGateway.substring(0, 2), 16)
+        ].join(".");
+        rewriteLogger.info("Host gateway IP from /proc/net/route", { ip });
+        cachedGatewayHost = ip;
+        return cachedGatewayHost;
+      }
+    }
+  } catch {
+    rewriteLogger.debug("Could not read /proc/net/route for default gateway lookup");
+  }
+  try {
+    const hosts = readFileSync("/etc/hosts", "utf-8");
+    for (const line of hosts.split("\n")) {
+      const trimmed = line.trim();
+      if (trimmed.startsWith("#") || trimmed === "") continue;
+      const parts = trimmed.split(/\s+/);
+      if (parts.length >= 2 && parts.slice(1).includes("host.docker.internal")) {
+        const ip = parts[0];
+        rewriteLogger.info("Host gateway IP from /etc/hosts (host.docker.internal)", { ip });
+        cachedGatewayHost = ip;
+        return cachedGatewayHost;
+      }
+    }
+  } catch {
+    rewriteLogger.debug("Could not read /etc/hosts for host.docker.internal lookup");
+  }
+  rewriteLogger.warn("Could not resolve host gateway \u2014 localhost URLs will not be rewritten");
+  cachedGatewayHost = null;
+  return cachedGatewayHost;
+}
+function rewriteLocalhostUrl(url) {
+  if (!isVMEnvironment()) {
+    return url;
+  }
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return url;
+  }
+  if (!LOCALHOST_HOSTS.has(parsed.hostname)) {
+    return url;
+  }
+  const gatewayHost = resolveHostGateway();
+  if (!gatewayHost) {
+    return url;
+  }
+  parsed.hostname = gatewayHost;
+  const rewritten = parsed.toString();
+  rewriteLogger.debug("Rewrote localhost URL", {
+    original: url,
+    rewritten,
+    gatewayHost
+  });
+  return rewritten;
+}
+function _resetGatewayCache() {
+  cachedGatewayHost = void 0;
+}
+export {
+  _resetGatewayCache,
+  isVMEnvironment,
+  resolveHostGateway,
+  rewriteLocalhostUrl
+};
+//# sourceMappingURL=host-rewrite.mjs.map

package/dist/host-rewrite.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/logging/plugin-logger.ts","../src/logging/index.ts","../src/host-rewrite.ts"],"sourcesContent":["/**\n * Plugin Logger Bridge\n *\n * Provides a logger factory for plugins that automatically bridges\n * to Quilltap's core logging when running inside the host application,\n * or falls back to console logging when running standalone.\n *\n * @module @quilltap/plugin-utils/logging/plugin-logger\n */\n\nimport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n/**\n * Extended logger interface with child logger support\n */\nexport interface PluginLoggerWithChild extends PluginLogger {\n  /**\n   * Create a child logger with additional context\n   * @param additionalContext Context to merge with parent context\n   * @returns A new logger with combined context\n   */\n  child(additionalContext: LogContext): PluginLoggerWithChild;\n}\n\n/**\n * Type for the global Quilltap logger bridge\n * Stored on globalThis to work across different npm package copies\n */\ndeclare global {\n   \n  var __quilltap_logger_factory:\n    | ((pluginName: string) => PluginLoggerWithChild)\n    | undefined;\n}\n\n/**\n * Get the core logger factory from global namespace\n *\n * @returns The injected factory or null if not in Quilltap environment\n */\nfunction getCoreLoggerFactory(): ((pluginName: string) => PluginLoggerWithChild) | null {\n  return globalThis.__quilltap_logger_factory ?? null;\n}\n\n/**\n * Inject the core logger factory from Quilltap host\n *\n * This is called by Quilltap core when loading plugins to bridge\n * plugin logging into the host's logging system. Uses globalThis\n * to ensure it works even when plugins have their own copy of\n * plugin-utils in their node_modules.\n *\n * **Internal API - not for plugin use**\n *\n * @param factory A function that creates a child logger for a plugin\n */\nexport function __injectCoreLoggerFactory(\n  factory: (pluginName: string) => PluginLoggerWithChild\n): void {\n  globalThis.__quilltap_logger_factory = factory;\n}\n\n/**\n * Clear the injected core logger factory\n *\n * Useful for testing or when unloading the plugin system.\n *\n * **Internal API - not for plugin use**\n */\nexport function __clearCoreLoggerFactory(): void {\n  globalThis.__quilltap_logger_factory = undefined;\n}\n\n/**\n * Check if a core logger has been injected\n *\n * @returns True if running inside Quilltap with core logging available\n */\nexport function hasCoreLogger(): boolean {\n  return getCoreLoggerFactory() !== null;\n}\n\n/**\n * Create a console logger with child support\n *\n * @param prefix Logger prefix\n * @param minLevel Minimum log level\n * @param baseContext Base context to include in all logs\n */\nfunction createConsoleLoggerWithChild(\n  prefix: string,\n  minLevel: LogLevel = 'debug',\n  baseContext: LogContext = {}\n): PluginLoggerWithChild {\n  const levels: LogLevel[] = ['debug', 'info', 'warn', 'error'];\n  const shouldLog = (level: LogLevel): boolean =>\n    levels.indexOf(level) >= levels.indexOf(minLevel);\n\n  const formatContext = (context?: LogContext): string => {\n    const merged = { ...baseContext, ...context };\n    const entries = Object.entries(merged)\n      .filter(([key]) => key !== 'context')\n      .map(([key, value]) => `${key}=${JSON.stringify(value)}`)\n      .join(' ');\n    return entries ? ` ${entries}` : '';\n  };\n\n  const logger: PluginLoggerWithChild = {\n    debug: (message: string, context?: LogContext): void => {\n      if (shouldLog('debug')) {\n        console.debug(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    info: (message: string, context?: LogContext): void => {\n      if (shouldLog('info')) {\n        console.info(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    warn: (message: string, context?: LogContext): void => {\n      if (shouldLog('warn')) {\n        console.warn(`[${prefix}] ${message}${formatContext(context)}`);\n      }\n    },\n\n    error: (message: string, context?: LogContext, error?: Error): void => {\n      if (shouldLog('error')) {\n        console.error(\n          `[${prefix}] ${message}${formatContext(context)}`,\n          error ? `\\n${error.stack || error.message}` : ''\n        );\n      }\n    },\n\n    child: (additionalContext: LogContext): PluginLoggerWithChild => {\n      return createConsoleLoggerWithChild(prefix, minLevel, {\n        ...baseContext,\n        ...additionalContext,\n      });\n    },\n  };\n\n  return logger;\n}\n\n/**\n * Create a plugin logger that bridges to Quilltap core logging\n *\n * When running inside Quilltap:\n * - Routes all logs to the core logger\n * - Tags logs with `{ plugin: pluginName, module: 'plugin' }`\n * - Logs appear in Quilltap's combined.log and console\n *\n * When running standalone:\n * - Falls back to console logging with `[pluginName]` prefix\n * - Respects the specified minimum log level\n *\n * @param pluginName - The plugin identifier (e.g., 'qtap-plugin-openai')\n * @param minLevel - Minimum log level when running standalone (default: 'debug')\n * @returns A logger instance\n *\n * @example\n * ```typescript\n * // In your plugin's provider.ts\n * import { createPluginLogger } from '@quilltap/plugin-utils';\n *\n * const logger = createPluginLogger('qtap-plugin-my-provider');\n *\n * export class MyProvider implements LLMProvider {\n *   async sendMessage(params: LLMParams, apiKey: string): Promise<LLMResponse> {\n *     logger.debug('Sending message', { model: params.model });\n *\n *     try {\n *       const response = await this.client.chat({...});\n *       logger.info('Received response', { tokens: response.usage?.total_tokens });\n *       return response;\n *     } catch (error) {\n *       logger.error('Failed to send message', { model: params.model }, error as Error);\n *       throw error;\n *     }\n *   }\n * }\n * ```\n */\nexport function createPluginLogger(\n  pluginName: string,\n  minLevel: LogLevel = 'debug'\n): PluginLoggerWithChild {\n  // Check for core logger factory from global namespace\n  const coreFactory = getCoreLoggerFactory();\n  if (coreFactory) {\n    return coreFactory(pluginName);\n  }\n\n  // Standalone mode: use enhanced console logger\n  return createConsoleLoggerWithChild(pluginName, minLevel);\n}\n\n/**\n * Get the minimum log level from environment\n *\n * Checks for LOG_LEVEL or QUILLTAP_LOG_LEVEL environment variables.\n * Useful for configuring standalone plugin logging.\n *\n * @returns The configured log level, or 'info' as default\n */\nexport function getLogLevelFromEnv(): LogLevel {\n  if (typeof process !== 'undefined' && process.env) {\n    const envLevel = process.env.LOG_LEVEL || process.env.QUILLTAP_LOG_LEVEL;\n    if (envLevel && ['debug', 'info', 'warn', 'error'].includes(envLevel)) {\n      return envLevel as LogLevel;\n    }\n  }\n  return 'info';\n}\n","/**\n * Logging Utilities\n *\n * Exports the plugin logger bridge and related utilities.\n *\n * @module @quilltap/plugin-utils/logging\n */\n\nexport {\n  createPluginLogger,\n  hasCoreLogger,\n  getLogLevelFromEnv,\n  __injectCoreLoggerFactory,\n  __clearCoreLoggerFactory,\n} from './plugin-logger';\n\nexport type { PluginLoggerWithChild } from './plugin-logger';\n\n// Re-export logger types from plugin-types\nexport type { PluginLogger, LogContext, LogLevel } from '@quilltap/plugin-types';\n\n// Re-export logger utilities from plugin-types for convenience\nexport { createConsoleLogger, createNoopLogger } from '@quilltap/plugin-types';\n","/**\n * Host URL Rewriting for VM/Container Environments\n *\n * When Quilltap runs inside Docker, Lima VMs, or WSL2, `localhost` and\n * `127.0.0.1` resolve to the container/VM's own loopback — not the host\n * machine where services like Ollama or LM Studio are running.\n *\n * This module provides a single function that transparently rewrites\n * localhost URLs to point at the host, so users can configure\n * `http://localhost:11434` and have it Just Work in every environment.\n *\n * Gateway resolution order:\n * 1. `QUILLTAP_HOST_IP` env var (explicit override) → rewrite to that IP\n * 2. In Docker (not Lima): rewrite `localhost` → `host.docker.internal`\n *    (Docker Desktop DNS or --add-host on Linux handles the forwarding)\n * 3. Default gateway from /proc/net/route (works in Lima and WSL2 where\n *    NAT networking forwards to host loopback)\n * 4. Fallback: try DNS lookup of `host.docker.internal` via /etc/hosts\n * 5. Give up gracefully — return URL unchanged\n *\n * @module @quilltap/plugin-utils/host-rewrite\n */\n\nimport { createPluginLogger } from './logging';\nimport { readFileSync, existsSync, statSync } from 'node:fs';\n\n// ============================================================================\n// Types\n// ============================================================================\n\n/** Hostnames that refer to the local loopback */\nconst LOCALHOST_HOSTS = new Set([\n  'localhost',\n  '127.0.0.1',\n  '[::1]',\n  '::1',\n]);\n\n// ============================================================================\n// Cached Gateway Host\n// ============================================================================\n\nlet cachedGatewayHost: string | null | undefined; // undefined = not yet resolved\n\nconst rewriteLogger = createPluginLogger('host-rewrite');\n\n// ============================================================================\n// Environment Detection (self-contained)\n// ============================================================================\n\n/**\n * Check if running inside a Lima VM.\n *\n * Lima VMs are provisioned with LIMA_CONTAINER=true in /etc/profile.d/quilltap.sh.\n */\nfunction isLimaEnvironment(): boolean {\n  return process.env.LIMA_CONTAINER === 'true';\n}\n\n/**\n * Check if running in a Docker container.\n *\n * Detects Docker by checking:\n * 1. DOCKER_CONTAINER environment variable\n * 2. Existence of /.dockerenv file\n * 3. Existence of /app directory (Quilltap Docker convention)\n */\nfunction isDockerEnvironment(): boolean {\n  if (process.env.DOCKER_CONTAINER === 'true') {\n    return true;\n  }\n\n  // Check for Docker-specific markers\n  try {\n    if (existsSync('/.dockerenv')) {\n      return true;\n    }\n    // Check for /app as a directory (Quilltap Docker convention)\n    const appStat = statSync('/app');\n    if (appStat.isDirectory()) {\n      return true;\n    }\n  } catch {\n    // Not in Docker\n  }\n\n  return false;\n}\n\n// ============================================================================\n// Public API\n// ============================================================================\n\n/**\n * Check if running in any VM or container environment that needs URL rewriting.\n */\nexport function isVMEnvironment(): boolean {\n  return isDockerEnvironment() || isLimaEnvironment();\n}\n\n/**\n * Resolve the host gateway address (IP or hostname).\n *\n * Tries multiple strategies in order; caches the result so file reads\n * only happen once per process lifetime.\n */\nexport function resolveHostGateway(): string | null {\n  // Return cached result if already resolved\n  if (cachedGatewayHost !== undefined) {\n    return cachedGatewayHost;\n  }\n\n  // Strategy 1: Explicit env var override\n  const envIP = process.env.QUILLTAP_HOST_IP;\n  if (envIP) {\n    rewriteLogger.info('Host gateway from QUILLTAP_HOST_IP', { host: envIP });\n    cachedGatewayHost = envIP;\n    return cachedGatewayHost;\n  }\n\n  // Strategy 2: Docker — use host.docker.internal directly as a hostname\n  // Docker Desktop (macOS/Windows) provides built-in DNS resolution for\n  // host.docker.internal via its DNS server (127.0.0.11).  Linux Docker\n  // needs --add-host=host.docker.internal:host-gateway (handled by the\n  // start scripts).  Either way, host.docker.internal correctly forwards\n  // to services bound to the host's loopback (127.0.0.1).\n  //\n  // This MUST run before /proc/net/route for Docker because the bridge\n  // gateway IP returned by /proc/net/route (e.g. 172.17.0.1) is just\n  // the Docker bridge interface — services listening on the host's\n  // localhost are NOT reachable through it.\n  //\n  // Lima VMs are excluded here: they trigger isDockerEnvironment() (they\n  // have /app) but don't have host.docker.internal in DNS.  Lima uses\n  // VZ NAT networking where the /proc/net/route gateway genuinely\n  // forwards to the host loopback.\n  if (isDockerEnvironment() && !isLimaEnvironment()) {\n    rewriteLogger.info('Docker environment detected — using host.docker.internal as gateway hostname');\n    cachedGatewayHost = 'host.docker.internal';\n    return cachedGatewayHost;\n  }\n\n  // Strategy 3: Default gateway from /proc/net/route (Lima/WSL2)\n  // Parse the kernel routing table directly instead of shelling out to\n  // `ip route`, which is unavailable in Alpine Linux images.\n  // The file format is tab-separated with hex-encoded IPs.\n  // This works for Lima and WSL2 where NAT networking forwards traffic\n  // from the gateway IP to the host's loopback.\n  try {\n    const routeTable = readFileSync('/proc/net/route', 'utf-8');\n    for (const line of routeTable.split('\\n').slice(1)) { // skip header\n      const fields = line.trim().split('\\t');\n      // fields[1] = Destination, fields[2] = Gateway\n      // Default route has destination 00000000\n      if (fields.length >= 3 && fields[1] === '00000000') {\n        const hexGateway = fields[2];\n        // Convert hex gateway to dotted-quad IP (little-endian on Linux)\n        const ip = [\n          parseInt(hexGateway.substring(6, 8), 16),\n          parseInt(hexGateway.substring(4, 6), 16),\n          parseInt(hexGateway.substring(2, 4), 16),\n          parseInt(hexGateway.substring(0, 2), 16),\n        ].join('.');\n        rewriteLogger.info('Host gateway IP from /proc/net/route', { ip });\n        cachedGatewayHost = ip;\n        return cachedGatewayHost;\n      }\n    }\n  } catch {\n    rewriteLogger.debug('Could not read /proc/net/route for default gateway lookup');\n  }\n\n  // Strategy 4: Fallback — resolve host.docker.internal from /etc/hosts\n  // Covers edge cases where Docker adds it to /etc/hosts but we're not\n  // detected as Docker (e.g., custom container runtimes).\n  try {\n    const hosts = readFileSync('/etc/hosts', 'utf-8');\n    for (const line of hosts.split('\\n')) {\n      const trimmed = line.trim();\n      if (trimmed.startsWith('#') || trimmed === '') continue;\n      // /etc/hosts format: <IP> <hostname1> [hostname2] ...\n      const parts = trimmed.split(/\\s+/);\n      if (parts.length >= 2 && parts.slice(1).includes('host.docker.internal')) {\n        const ip = parts[0];\n        rewriteLogger.info('Host gateway IP from /etc/hosts (host.docker.internal)', { ip });\n        cachedGatewayHost = ip;\n        return cachedGatewayHost;\n      }\n    }\n  } catch {\n    rewriteLogger.debug('Could not read /etc/hosts for host.docker.internal lookup');\n  }\n\n  rewriteLogger.warn('Could not resolve host gateway — localhost URLs will not be rewritten');\n  cachedGatewayHost = null;\n  return cachedGatewayHost;\n}\n\n/**\n * Rewrite a localhost URL to point at the host gateway.\n *\n * No-ops when:\n * - Not running in a VM/container environment\n * - The URL doesn't point to localhost or 127.0.0.1\n * - Gateway resolution fails\n *\n * @param url The URL to potentially rewrite\n * @returns The original URL or a rewritten version with the gateway host\n */\nexport function rewriteLocalhostUrl(url: string): string {\n  // No-op on bare metal\n  if (!isVMEnvironment()) {\n    return url;\n  }\n\n  // Parse the URL to check the hostname\n  let parsed: URL;\n  try {\n    parsed = new URL(url);\n  } catch {\n    // Not a valid URL — return unchanged\n    return url;\n  }\n\n  // Check if hostname is a localhost variant\n  if (!LOCALHOST_HOSTS.has(parsed.hostname)) {\n    return url;\n  }\n\n  // Resolve the gateway host\n  const gatewayHost = resolveHostGateway();\n  if (!gatewayHost) {\n    return url;\n  }\n\n  // Rewrite the hostname\n  parsed.hostname = gatewayHost;\n  const rewritten = parsed.toString();\n\n  rewriteLogger.debug('Rewrote localhost URL', {\n    original: url,\n    rewritten,\n    gatewayHost,\n  });\n\n  return rewritten;\n}\n\n/**\n * Reset the cached gateway host (for testing).\n * @internal\n */\nexport function _resetGatewayCache(): void {\n  cachedGatewayHost = undefined;\n}\n"],"mappings":"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","names":[]}