@hamedb89/localghost 0.1.8 → 0.1.9

package/dist/index.js

@@ -19,7 +19,7 @@ function isProcessRunning(pid) {
   }
 }
 function emptyActivity() {
-  return { version: LOCALGHOST_ACTIVITY_VERSION, runs: [] };
+  return { version: LOCALGHOST_ACTIVITY_VERSION, runs: [], setups: [] };
 }
 function readLocalghostActivity(path = getLocalghostActivityPath()) {
   if (!existsSync(path)) return emptyActivity();
@@ -27,7 +27,8 @@ function readLocalghostActivity(path = getLocalghostActivityPath()) {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
     return {
       version: LOCALGHOST_ACTIVITY_VERSION,
-      runs: Array.isArray(parsed.runs) ? parsed.runs : []
+      runs: Array.isArray(parsed.runs) ? parsed.runs : [],
+      setups: Array.isArray(parsed.setups) ? parsed.setups : []
     };
   } catch {
     return emptyActivity();
@@ -42,22 +43,29 @@ function writeLocalghostActivity(activity, path = getLocalghostActivityPath()) {
 function createRunId(input, pid) {
   return `${input.projectName}:${input.mode}:${pid}:${Date.now()}`;
 }
+function createSetupId(input) {
+  return `${input.projectName}:${input.cwd}:${input.configPath ?? ""}`;
+}
 function pruneLocalghostActivity(path = getLocalghostActivityPath()) {
   const activity = readLocalghostActivity(path);
   const activeRuns = activity.runs.filter((run) => isProcessRunning(run.pid));
   const pruned = activeRuns.length !== activity.runs.length;
   if (pruned) {
-    writeLocalghostActivity({ version: LOCALGHOST_ACTIVITY_VERSION, runs: activeRuns }, path);
+    writeLocalghostActivity({ ...activity, version: LOCALGHOST_ACTIVITY_VERSION, runs: activeRuns }, path);
   }
   return {
     path,
     pruned,
-    runs: activeRuns
+    runs: activeRuns,
+    setups: activity.setups
   };
 }
 function listLocalghostRuns(path = getLocalghostActivityPath()) {
   return pruneLocalghostActivity(path).runs;
 }
+function listLocalghostSetups(path = getLocalghostActivityPath()) {
+  return pruneLocalghostActivity(path).setups;
+}
 function registerLocalghostRun(input, path = getLocalghostActivityPath()) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const pid = input.pid ?? process.pid;
@@ -81,14 +89,43 @@ function registerLocalghostRun(input, path = getLocalghostActivityPath()) {
     entries: input.entries
   };
   const current = pruneLocalghostActivity(path).runs.filter((run) => run.id !== record.id);
-  writeLocalghostActivity({ version: LOCALGHOST_ACTIVITY_VERSION, runs: [...current, record] }, path);
+  const activity = readLocalghostActivity(path);
+  writeLocalghostActivity({ version: LOCALGHOST_ACTIVITY_VERSION, runs: [...current, record], setups: activity.setups }, path);
+  return record;
+}
+function registerLocalghostSetup(input, path = getLocalghostActivityPath()) {
+  const record = {
+    id: input.id ?? createSetupId(input),
+    cwd: input.cwd,
+    projectName: input.projectName,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    ...input.configPath ? { configPath: input.configPath } : {},
+    ...input.caddyfilePath ? { caddyfilePath: input.caddyfilePath } : {},
+    ...typeof input.https === "boolean" ? { https: input.https } : {},
+    entries: input.entries
+  };
+  const activity = pruneLocalghostActivity(path);
+  const setups = activity.setups.filter((setup) => setup.id !== record.id);
+  writeLocalghostActivity({ version: LOCALGHOST_ACTIVITY_VERSION, runs: activity.runs, setups: [...setups, record] }, path);
   return record;
 }
 function unregisterLocalghostRun(id, path = getLocalghostActivityPath()) {
   const activity = readLocalghostActivity(path);
   const runs = activity.runs.filter((run) => run.id !== id);
   if (runs.length !== activity.runs.length) {
-    writeLocalghostActivity({ version: LOCALGHOST_ACTIVITY_VERSION, runs }, path);
+    writeLocalghostActivity({ ...activity, version: LOCALGHOST_ACTIVITY_VERSION, runs }, path);
+  }
+}
+function unregisterLocalghostSetup(options, path = getLocalghostActivityPath()) {
+  const activity = readLocalghostActivity(path);
+  const setups = activity.setups.filter((setup) => {
+    if (setup.cwd !== options.cwd) return true;
+    if (options.projectName && setup.projectName !== options.projectName) return true;
+    if (options.configPath && setup.configPath !== options.configPath) return true;
+    return false;
+  });
+  if (setups.length !== activity.setups.length) {
+    writeLocalghostActivity({ ...activity, version: LOCALGHOST_ACTIVITY_VERSION, setups }, path);
   }
 }
 
@@ -291,7 +328,8 @@ async function trustCaddy(path) {
 }
 
 // src/context.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
 import { pathToFileURL } from "url";
 
 // src/port.ts
@@ -320,6 +358,339 @@ async function findAvailablePort(startPort, options = {}) {
   throw new Error(`No available port found from ${startPort} to ${startPort + maxAttempts - 1}.`);
 }
 
+// src/tunnel.ts
+import { domainToASCII } from "url";
+var DEFAULT_GHOST_TUNNEL_SUBDOMAIN = "ghost";
+var DEFAULT_GHOST_TUNNEL_NAMESPACE_TAGS = ["route", "project", "owner"];
+var DEFAULT_GHOST_TUNNEL_NAMESPACE_SEPARATOR = "-";
+var DEFAULT_GHOST_TUNNEL_MODE = "manual";
+function isResolvedGhostTunnelConfig(value) {
+  return typeof value === "object" && value !== null && "enabled" in value;
+}
+function toGhostTunnelConfig(options) {
+  return isResolvedGhostTunnelConfig(options) ? options : resolveGhostTunnelConfig(options);
+}
+function stripHostPort(value) {
+  const trimmed = value.trim().toLowerCase();
+  if (trimmed.startsWith("[") || trimmed.includes("/")) return "";
+  const portSeparator = trimmed.lastIndexOf(":");
+  if (portSeparator === -1) return trimmed;
+  const port = trimmed.slice(portSeparator + 1);
+  return /^\d+$/.test(port) ? trimmed.slice(0, portSeparator) : trimmed;
+}
+function normalizeDomain(value) {
+  const host = stripHostPort(value.replace(/^\*\./, ""));
+  const ascii = domainToASCII(host);
+  if (!ascii || ascii.length > 253 || ascii.includes("..")) return null;
+  if (ascii.startsWith(".") || ascii.endsWith(".")) return null;
+  if (ascii.includes("*")) return null;
+  if (!ascii.split(".").every(isValidHostLabel)) return null;
+  return ascii;
+}
+function isValidHostLabel(value) {
+  return value.length > 0 && value.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(value);
+}
+function isValidNamespaceTag(value) {
+  return /^[a-z][a-z0-9_]*$/i.test(value);
+}
+function isNamespaceTagList(options) {
+  return Array.isArray(options);
+}
+function assertValidSubdomain(value) {
+  if (!isValidHostLabel(value)) {
+    throw new Error(`Invalid ghost tunnel subdomain: ${value}`);
+  }
+}
+function normalizeDomains(domains) {
+  const values = typeof domains === "string" ? [domains] : [...domains ?? []];
+  const normalized = values.map((value) => value.trim()).filter(Boolean).map((value) => {
+    const domain = normalizeDomain(value);
+    if (!domain) throw new Error(`Invalid ghost tunnel domain: ${value}`);
+    return domain;
+  });
+  return [...new Set(normalized)];
+}
+function parseGhostTunnelMode(value) {
+  return value ?? DEFAULT_GHOST_TUNNEL_MODE;
+}
+function resolveNamespaceConfig(options) {
+  const tags = isNamespaceTagList(options) ? [...options] : [...options?.tags ?? DEFAULT_GHOST_TUNNEL_NAMESPACE_TAGS];
+  let separator = DEFAULT_GHOST_TUNNEL_NAMESPACE_SEPARATOR;
+  let spreadTag = tags.includes("project") ? "project" : void 0;
+  if (options && !isNamespaceTagList(options)) {
+    separator = options.separator ?? DEFAULT_GHOST_TUNNEL_NAMESPACE_SEPARATOR;
+    spreadTag = options.spreadTag === false ? false : options.spreadTag ?? spreadTag;
+  }
+  if (tags.length === 0) {
+    throw new Error("Ghost tunnel namespace must include at least one tag.");
+  }
+  for (const tag of tags) {
+    if (!isValidNamespaceTag(tag)) {
+      throw new Error(`Invalid ghost tunnel namespace tag: ${tag}`);
+    }
+  }
+  if (spreadTag && !tags.includes(spreadTag)) {
+    throw new Error(`Ghost tunnel namespace spreadTag must be listed in tags: ${spreadTag}`);
+  }
+  if (!separator || separator.length > 8 || !/^[a-z0-9-]+$/.test(separator)) {
+    throw new Error(`Invalid ghost tunnel namespace separator: ${separator}`);
+  }
+  return {
+    tags,
+    separator,
+    ...spreadTag ? { spreadTag } : {}
+  };
+}
+function normalizeNamespaceValue(tag, value, separator, options = {}) {
+  const normalized = normalizeDomain(value);
+  if (!normalized || normalized.includes(".")) {
+    throw new Error(`Invalid ghost tunnel namespace value for ${tag}: ${value}`);
+  }
+  if (!options.allowSeparator && normalized.includes(separator)) {
+    throw new Error(`Ghost tunnel namespace value for ${tag} cannot include separator "${separator}": ${value}`);
+  }
+  return normalized;
+}
+function createNamespaceSlug(config, values) {
+  const parts = config.tags.map((tag) => {
+    const value = values[tag];
+    if (!value) {
+      throw new Error(`Missing ghost tunnel namespace value: ${tag}`);
+    }
+    return normalizeNamespaceValue(tag, value, config.separator, { allowSeparator: tag === config.spreadTag });
+  });
+  const slug = parts.join(config.separator);
+  if (!isValidHostLabel(slug)) {
+    throw new Error(`Ghost tunnel namespace is too long for a DNS label: ${slug}`);
+  }
+  return slug;
+}
+function createNamespaceDisplaySlug(config, values = {}) {
+  return config.tags.map((tag) => {
+    const value = values[tag];
+    if (!value) return `<${tag}>`;
+    try {
+      return normalizeNamespaceValue(tag, value, config.separator, { allowSeparator: tag === config.spreadTag });
+    } catch {
+      return `<${tag}>`;
+    }
+  }).join(config.separator);
+}
+function getPreviewDefaults(preview, defaults) {
+  return {
+    domain: preview?.domain ?? defaults?.domain,
+    route: preview?.route ?? defaults?.route,
+    project: preview?.project ?? defaults?.project,
+    owner: preview?.owner ?? defaults?.owner,
+    values: {
+      ...defaults?.values ?? {},
+      ...preview?.values ?? {}
+    },
+    path: preview?.path,
+    protocol: preview?.protocol
+  };
+}
+function getDisplayValues(input) {
+  return {
+    ...input.route ? { route: input.route } : {},
+    ...input.project ? { project: input.project } : {},
+    ...input.owner ? { owner: input.owner } : {},
+    ...input.values
+  };
+}
+function createDisplayUrl(config, defaults, domain) {
+  const input = getPreviewDefaults(config.preview, defaults);
+  const protocol = input.protocol ?? "https";
+  const slug = createNamespaceDisplaySlug(config.namespace, getDisplayValues(input));
+  const entryHost = domain ? getGhostTunnelEntryHost(domain, config) : input.domain ? getGhostTunnelEntryHost(input.domain, config) : `${config.subdomain}.*`;
+  const url = `${protocol}://${slug}.${entryHost}/`;
+  if (!input.path) return url;
+  return `${url}${input.path.replace(/^\/+/, "")}`;
+}
+function createDisplayUrls(config, defaults) {
+  const domains = config.domains.length > 0 ? config.domains : defaults?.domain ? [defaults.domain] : [];
+  const urls = domains.length > 0 ? domains.map((domain) => createDisplayUrl(config, defaults, domain)) : [createDisplayUrl(config, defaults)];
+  return [...new Set(urls)];
+}
+function maybeConstructPreviewUrl(config, defaults) {
+  if (!config.preview) return void 0;
+  const input = getPreviewDefaults(config.preview, defaults);
+  if (!input.domain || !input.route || !input.project || !input.owner) return void 0;
+  return constructGhostTunnelUrl({
+    domain: input.domain,
+    route: input.route,
+    project: input.project,
+    owner: input.owner,
+    values: input.values,
+    ...input.path ? { path: input.path } : {},
+    ...input.protocol ? { protocol: input.protocol } : {},
+    ghostTunnel: config
+  });
+}
+function parseNamespaceSlug(slug, config) {
+  const parts = slug.split(config.separator);
+  if (parts.length < config.tags.length) return null;
+  if (parts.length !== config.tags.length && !config.spreadTag) return null;
+  const namespace = {};
+  const spreadIndex = config.spreadTag ? config.tags.indexOf(config.spreadTag) : -1;
+  const spreadWidth = spreadIndex >= 0 ? parts.length - config.tags.length + 1 : 1;
+  let partIndex = 0;
+  for (const [tagIndex, tag] of config.tags.entries()) {
+    const value = tagIndex === spreadIndex ? parts.slice(partIndex, partIndex + spreadWidth).join(config.separator) : parts[partIndex];
+    if (!value || !isValidHostLabel(value)) return null;
+    if (tagIndex !== spreadIndex && value.includes(config.separator)) return null;
+    namespace[tag] = value;
+    partIndex += tagIndex === spreadIndex ? spreadWidth : 1;
+  }
+  return namespace;
+}
+function resolveGhostTunnelConfig(options, defaults) {
+  if (options === false || typeof options === "undefined") {
+    return {
+      enabled: false,
+      mode: DEFAULT_GHOST_TUNNEL_MODE,
+      domains: [],
+      subdomain: DEFAULT_GHOST_TUNNEL_SUBDOMAIN,
+      namespace: resolveNamespaceConfig(void 0),
+      displayUrls: [],
+      requireHttps: true,
+      requireAuth: true
+    };
+  }
+  const config = typeof options === "string" ? { mode: options } : options;
+  const subdomain = config.subdomain ?? DEFAULT_GHOST_TUNNEL_SUBDOMAIN;
+  assertValidSubdomain(subdomain);
+  const domains = normalizeDomains(config.domains);
+  const enabled = config.enabled ?? true;
+  const resolved = {
+    enabled,
+    mode: parseGhostTunnelMode(config.mode),
+    domains,
+    subdomain,
+    namespace: resolveNamespaceConfig(config.namespace),
+    ...config.preview ? { preview: config.preview } : {},
+    displayUrls: [],
+    requireHttps: config.requireHttps ?? true,
+    requireAuth: config.requireAuth ?? true
+  };
+  if (!enabled) {
+    return resolved;
+  }
+  const previewUrl = maybeConstructPreviewUrl(resolved, defaults);
+  const displayUrls = previewUrl ? [previewUrl] : createDisplayUrls(resolved, defaults);
+  return {
+    ...resolved,
+    displayUrls,
+    ...displayUrls[0] ? { displayUrl: displayUrls[0] } : {},
+    ...previewUrl ? { previewUrl } : {}
+  };
+}
+function getGhostTunnelEntryHost(domain, options = {}) {
+  const config = toGhostTunnelConfig(options);
+  const normalizedDomain = normalizeDomain(domain);
+  if (!normalizedDomain) {
+    throw new Error(`Invalid ghost tunnel domain: ${domain}`);
+  }
+  return `${config.subdomain}.${normalizedDomain}`;
+}
+function getGhostTunnelWildcardHost(domain, options = {}) {
+  return `*.${getGhostTunnelEntryHost(domain, options)}`;
+}
+function constructGhostTunnelHost(input) {
+  const config = toGhostTunnelConfig(input.ghostTunnel ?? {});
+  if (!config.enabled) {
+    throw new Error("Ghost tunnel is not enabled.");
+  }
+  const namespaceValues = {
+    route: input.route,
+    project: input.project,
+    owner: input.owner,
+    ...input.values ?? {}
+  };
+  const slug = createNamespaceSlug(config.namespace, namespaceValues);
+  return `${slug}.${getGhostTunnelEntryHost(input.domain, config)}`;
+}
+function constructGhostTunnelUrl(input) {
+  const protocol = input.protocol ?? "https";
+  const host = constructGhostTunnelHost(input);
+  const url = new URL(`${protocol}://${host}/`);
+  if (input.path) {
+    url.pathname = `/${input.path.replace(/^\/+/, "")}`;
+  }
+  if (input.searchParams instanceof URLSearchParams) {
+    url.search = input.searchParams.toString();
+  } else if (input.searchParams) {
+    for (const [key, value] of Object.entries(input.searchParams)) {
+      if (typeof value !== "undefined" && value !== null) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+  }
+  return url.toString();
+}
+var constructGhostTunnelURL = constructGhostTunnelUrl;
+function getGhostTunnelDefaultDisplayUrl(options = {}, defaults) {
+  const config = toGhostTunnelConfig(options);
+  if (!config.enabled) return null;
+  return createDisplayUrl(config, defaults);
+}
+function getGhostTunnelDisplayUrl(options, defaults) {
+  const config = toGhostTunnelConfig(options);
+  if (!config.enabled) return null;
+  return config.displayUrl ?? config.previewUrl ?? getGhostTunnelDefaultDisplayUrl(config, defaults);
+}
+function getGhostTunnelDisplayUrls(options, defaults) {
+  const config = toGhostTunnelConfig(options);
+  if (!config.enabled) return [];
+  if (config.displayUrls.length > 0) return config.displayUrls;
+  const displayUrl = getGhostTunnelDisplayUrl(config, defaults);
+  return displayUrl ? [displayUrl] : [];
+}
+function getGhostTunnelPreviewUrl(options) {
+  const config = toGhostTunnelConfig(options);
+  if (!config.enabled) return null;
+  return config.previewUrl ?? maybeConstructPreviewUrl(config) ?? null;
+}
+function parseGhostTunnelHost(host, domain, options = {}) {
+  const config = toGhostTunnelConfig(options);
+  if (!config.enabled) return null;
+  const normalizedHost = normalizeDomain(host);
+  const normalizedDomain = normalizeDomain(domain);
+  if (!normalizedHost || !normalizedDomain) return null;
+  const entryHost = getGhostTunnelEntryHost(normalizedDomain, config);
+  const suffix = `.${entryHost}`;
+  if (!normalizedHost.endsWith(suffix)) return null;
+  const slug = normalizedHost.slice(0, -suffix.length);
+  if (!isValidHostLabel(slug)) return null;
+  const namespace = parseNamespaceSlug(slug, config.namespace);
+  if (!namespace) return null;
+  return {
+    host: normalizedHost,
+    slug,
+    namespace,
+    entryHost,
+    wildcardHost: `*.${entryHost}`,
+    domain: normalizedDomain
+  };
+}
+function assertSecureGhostTunnelRequest(input) {
+  const config = toGhostTunnelConfig(input.ghostTunnel);
+  if (!config.enabled) {
+    throw new Error("Ghost tunnel is not enabled.");
+  }
+  if (config.requireHttps && input.protocol !== "https") {
+    throw new Error("Ghost tunnel requests must use HTTPS.");
+  }
+  if (config.requireAuth && input.authenticated !== true) {
+    throw new Error("Ghost tunnel requests must be authenticated.");
+  }
+  const route = parseGhostTunnelHost(input.host, input.domain, config);
+  if (!route) {
+    throw new Error(`Host is not a valid ghost tunnel host for ${input.domain}.`);
+  }
+  return route;
+}
+
 // src/context.ts
 var LOCALGHOST_PROJECT_CONFIG_FILES = [
   "localghost.config.mjs",
@@ -344,6 +715,25 @@ function envHttps() {
   if (!value) return void 0;
   return ["1", "true", "yes", "on"].includes(value.toLowerCase());
 }
+function getPackageName(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync4(join4(cwd, "package.json"), "utf8"));
+    return typeof pkg.name === "string" ? pkg.name : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getPackageOwner(cwd) {
+  const packageName = getPackageName(cwd);
+  if (!packageName?.startsWith("@")) return void 0;
+  return packageName.slice(1).split("/")[0];
+}
+function getLocalOwner(cwd) {
+  return sanitizeProjectName(process.env.LOCALGHOST_OWNER ?? getPackageOwner(cwd) ?? process.env.USER ?? process.env.USERNAME ?? "local");
+}
+function getRouteName(primaryHost, fallback) {
+  return sanitizeProjectName(primaryHost.split(".")[0] ?? fallback);
+}
 function readOptionsFromContext(options) {
   return {
     cwd: options.cwd ?? process.cwd(),
@@ -382,11 +772,12 @@ function addDefaultWwwAliases(entries) {
 function defined(input) {
   return Object.fromEntries(Object.entries(input).filter(([, value]) => typeof value !== "undefined"));
 }
-async function readProjectConfig(cwd, configFile) {
-  if (configFile === false) return {};
-  const candidates = configFile ? [configFile] : LOCALGHOST_PROJECT_CONFIG_FILES;
+async function readLocalghostProjectConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  if (options.configFile === false) return { config: {} };
+  const candidates = options.configFile ? [options.configFile] : LOCALGHOST_PROJECT_CONFIG_FILES;
   const path = candidates.map((candidate) => resolveDevHostsPath({ cwd, fileName: candidate }).path).find((candidate) => existsSync3(candidate));
-  if (!path) return {};
+  if (!path) return { config: {} };
   const imported = await import(`${pathToFileURL(path).href}?localghost=${Date.now()}`);
   const config = imported.default ?? imported;
   return { config, path };
@@ -396,7 +787,10 @@ function defineLocalghostConfig(config) {
 }
 async function resolveLocalghostContext(options = {}) {
   const cwd = options.cwd ?? process.cwd();
-  const projectConfig = await readProjectConfig(cwd, options.localghostConfig);
+  const projectConfig = await readLocalghostProjectConfig({
+    cwd,
+    ...typeof options.localghostConfig !== "undefined" ? { configFile: options.localghostConfig } : {}
+  });
   const merged = {
     ...projectConfig.config,
     ...defined(options)
@@ -405,7 +799,7 @@ async function resolveLocalghostContext(options = {}) {
   const resolvedPath = resolveDevHostsPath(readOptions);
   const configEntries = readDevHosts(readOptions);
   const requestedPort = merged.port ?? envPort() ?? configEntries[0]?.port ?? 5173;
-  const dynamicPort = merged.dynamicPort ?? envDynamicPort() ?? false;
+  const dynamicPort = merged.dynamicPort ?? envDynamicPort() ?? true;
   const bindHost = merged.bindHost ?? "127.0.0.1";
   const probeHost = typeof bindHost === "string" ? bindHost : "127.0.0.1";
   const port = dynamicPort ? await findAvailablePort(requestedPort, { host: probeHost }) : requestedPort;
@@ -413,9 +807,15 @@ async function resolveLocalghostContext(options = {}) {
   const entries = wwwAlias ? addDefaultWwwAliases(withRuntimePort(configEntries, requestedPort, port)) : withRuntimePort(configEntries, requestedPort, port);
   const hosts = uniqueHosts(entries);
   const primaryHost = merged.primaryHost ?? entries.find((entry) => entry.port === port)?.host ?? hosts[0] ?? `${sanitizeProjectName(getProjectName(cwd))}.localhost`;
+  const projectName = sanitizeProjectName(merged.project ?? getProjectName(cwd));
+  const ghostTunnel = resolveGhostTunnelConfig(merged.ghostTunnel, {
+    route: getRouteName(primaryHost, projectName),
+    project: projectName,
+    owner: getLocalOwner(cwd)
+  });
   return {
     cwd,
-    projectName: sanitizeProjectName(merged.project ?? getProjectName(cwd)),
+    projectName,
     readOptions,
     configPath: resolvedPath.path,
     configFileName: resolvedPath.fileName,
@@ -429,6 +829,7 @@ async function resolveLocalghostContext(options = {}) {
     primaryHost,
     https: merged.https ?? envHttps() ?? false,
     wwwAlias,
+    ghostTunnel,
     ...projectConfig.path ? { projectConfigPath: projectConfig.path } : {}
   };
 }
@@ -486,7 +887,7 @@ function getProductionEnvKeys() {
 // src/hosts-file.ts
 import { writeFileSync as writeFileSync3 } from "fs";
 import { tmpdir } from "os";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { execa as execa3 } from "execa";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -528,7 +929,7 @@ function removeManagedBlock(existing, projectName) {
 }
 async function writeSystemHostsFile(hostsPath, next, projectName) {
   const sanitizedProjectName = sanitizeProjectName(projectName);
-  const tempPath = join4(tmpdir(), `localghost-${sanitizedProjectName}-hosts`);
+  const tempPath = join5(tmpdir(), `localghost-${sanitizedProjectName}-hosts`);
   writeFileSync3(tempPath, next, "utf8");
   if (process.platform === "win32") {
     throw new Error(`Windows support: run as administrator and copy ${tempPath} to ${hostsPath}.`);
@@ -561,11 +962,11 @@ async function removeSystemHosts(projectName) {
 }
 
 // src/init.ts
-import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
-import { join as join5 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
+import { join as join6 } from "path";
 function detectPackageManager(cwd = process.cwd()) {
-  if (existsSync4(join5(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync4(join5(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync4(join6(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync4(join6(cwd, "yarn.lock"))) return "yarn";
   return "npm";
 }
 function packageRunCommand(packageManager, script) {
@@ -590,7 +991,7 @@ function renderConfig(options) {
 }
 function readPackageJson(path) {
   try {
-    return JSON.parse(readFileSync4(path, "utf8"));
+    return JSON.parse(readFileSync5(path, "utf8"));
   } catch {
     return null;
   }
@@ -642,7 +1043,7 @@ function initLocalghost(options = {}) {
   const apiPort = options.apiPort ?? 8787;
   const packageManager = options.packageManager ?? detectPackageManager(cwd);
   const configFile = options.configFile ?? LOCALGHOST_CONFIG_FILE;
-  const configPath = join5(cwd, configFile);
+  const configPath = join6(cwd, configFile);
   const configExists = existsSync4(configPath);
   if (configExists && !options.force) {
     return {
@@ -659,7 +1060,7 @@ function initLocalghost(options = {}) {
     };
   }
   writeTextFile(configPath, renderConfig({ host, port, apiHost, apiPort }));
-  const packageJsonPath = join5(cwd, "package.json");
+  const packageJsonPath = join6(cwd, "package.json");
   const packageJsonChanged = options.writeScripts ? updatePackageScripts(packageJsonPath, configFile) : false;
   return {
     configPath,
@@ -676,7 +1077,277 @@ function initLocalghost(options = {}) {
   };
 }
 
+// src/relay.ts
+import { createHmac, timingSafeEqual } from "crypto";
+import { domainToASCII as domainToASCII2 } from "url";
+var DEFAULT_RELAY_ALLOWED_TARGET_HOSTS = ["localhost", "127.0.0.1", "::1"];
+var DEFAULT_RELAY_BLOCKED_PORTS = [22, 2375, 2376, 5432, 6379, 9200, 9229, 27017];
+var DEFAULT_RELAY_LIMITS = {
+  requestBodyBytes: 5 * 1024 * 1024,
+  responseBytes: 25 * 1024 * 1024,
+  timeoutMs: 3e4,
+  maxConcurrentRequests: 20,
+  perRouteRequestsPerMinute: 120,
+  perIpRequestsPerMinute: 60
+};
+var DEFAULT_RELAY_TARGET_POLICY = {
+  allowedHosts: [...DEFAULT_RELAY_ALLOWED_TARGET_HOSTS],
+  blockedPorts: [...DEFAULT_RELAY_BLOCKED_PORTS],
+  allowPrivateNetworkTargets: false
+};
+var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+]);
+var SENSITIVE_HEADERS = /* @__PURE__ */ new Set(["authorization", "cookie", "set-cookie"]);
+var TOKEN_QUERY_PATTERN = /(token|secret|key|password|session|jwt|auth)/i;
+var HOST_PATTERN2 = /^(?=.{1,253}$)(?!-)[a-z0-9-]+(\.[a-z0-9-]+)*$/i;
+var IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+function base64UrlEncode(value) {
+  return Buffer.from(value).toString("base64url");
+}
+function base64UrlDecode(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+function signPayload(payload, secret) {
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+function secureEqual(left, right) {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}
+function normalizeHost(host) {
+  const trimmed = host.trim().toLowerCase().replace(/\.$/, "");
+  if (!trimmed || trimmed.includes("*") || trimmed.includes("/") || trimmed.includes(":")) return null;
+  const ascii = domainToASCII2(trimmed);
+  if (!ascii || ascii.includes("..")) return null;
+  return HOST_PATTERN2.test(ascii) ? ascii : null;
+}
+function normalizeTargetHost(host) {
+  const trimmed = host.trim().toLowerCase();
+  if (trimmed === "::1" || trimmed === "[::1]") return "::1";
+  if (trimmed.includes("/") || trimmed.includes("*")) return null;
+  if (IPV4_PATTERN.test(trimmed)) return isValidIpv4(trimmed) ? trimmed : null;
+  return normalizeHost(trimmed);
+}
+function isValidIpv4(value) {
+  return value.split(".").every((part) => {
+    const octet = Number(part);
+    return Number.isInteger(octet) && octet >= 0 && octet <= 255 && String(octet) === part;
+  });
+}
+function isPrivateIpv4(value) {
+  if (!isValidIpv4(value)) return false;
+  const [first = 0, second = 0] = value.split(".").map((part) => Number(part));
+  return first === 10 || first === 127 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168 || first === 169 && second === 254;
+}
+function isLocalTargetHost(host) {
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+function mergeTargetPolicy(policy) {
+  return {
+    allowedHosts: policy?.allowedHosts ?? DEFAULT_RELAY_TARGET_POLICY.allowedHosts,
+    blockedPorts: policy?.blockedPorts ?? DEFAULT_RELAY_TARGET_POLICY.blockedPorts,
+    allowPrivateNetworkTargets: policy?.allowPrivateNetworkTargets ?? DEFAULT_RELAY_TARGET_POLICY.allowPrivateNetworkTargets
+  };
+}
+function mergeLimits(limits) {
+  const merged = {
+    ...DEFAULT_RELAY_LIMITS,
+    ...limits ?? {}
+  };
+  for (const [key, value] of Object.entries(merged)) {
+    if (!Number.isInteger(value) || value < 1) {
+      throw new Error(`Invalid relay limit ${key}: ${value}`);
+    }
+  }
+  return merged;
+}
+function assertExactRelayHost(host) {
+  const normalized = normalizeHost(host);
+  if (!normalized) {
+    throw new Error(`Relay route claims must use an exact hostname: ${host}`);
+  }
+  return normalized;
+}
+function assertRelayLocalTarget(target, policyInput) {
+  if (!target || typeof target !== "object") {
+    throw new Error("Relay target must be an explicit local target object.");
+  }
+  const policy = mergeTargetPolicy(policyInput);
+  const host = normalizeTargetHost(target.host);
+  if (!host) {
+    throw new Error(`Invalid relay target host: ${target.host}`);
+  }
+  if (!Number.isInteger(target.port) || target.port < 1 || target.port > 65535) {
+    throw new Error(`Invalid relay target port: ${target.port}`);
+  }
+  const protocol = target.protocol ?? "http";
+  if (protocol !== "http" && protocol !== "https") {
+    throw new Error(`Invalid relay target protocol: ${String(protocol)}`);
+  }
+  if (policy.blockedPorts.includes(target.port)) {
+    throw new Error(`Relay target port is blocked: ${target.port}`);
+  }
+  const allowedHosts = new Set(policy.allowedHosts.map((allowedHost) => normalizeTargetHost(allowedHost)).filter((value) => Boolean(value)));
+  if (!allowedHosts.has(host)) {
+    throw new Error(`Relay target host is not explicitly allowed: ${host}`);
+  }
+  if (!policy.allowPrivateNetworkTargets && !isLocalTargetHost(host) && (host === "::1" || isPrivateIpv4(host))) {
+    throw new Error(`Private-network relay target requires explicit opt-in: ${host}`);
+  }
+  return {
+    protocol,
+    host,
+    port: target.port
+  };
+}
+function authenticateRelayAgentToken(input) {
+  const expected = `Bearer ${input.agentToken}`;
+  return typeof input.authorizationHeader === "string" && secureEqual(input.authorizationHeader, expected);
+}
+function signRelayRouteClaim(claim, signingSecret) {
+  const payload = {
+    ...claim,
+    host: assertExactRelayHost(claim.host)
+  };
+  if (!payload.scope) throw new Error("Relay route claim requires a scope.");
+  if (!payload.agentId) throw new Error("Relay route claim requires an agentId.");
+  if (Number.isNaN(Date.parse(payload.expiresAt))) throw new Error("Relay route claim requires a valid expiresAt.");
+  const encodedPayload = base64UrlEncode(JSON.stringify(payload));
+  const signature = signPayload(encodedPayload, signingSecret);
+  return {
+    payload,
+    token: `${encodedPayload}.${signature}`
+  };
+}
+function verifyRelayRouteClaim(token, signingSecret, options) {
+  const [encodedPayload, signature] = token.split(".");
+  if (!encodedPayload || !signature || token.split(".").length !== 2) {
+    throw new Error("Invalid relay route claim token.");
+  }
+  const expectedSignature = signPayload(encodedPayload, signingSecret);
+  if (!secureEqual(signature, expectedSignature)) {
+    throw new Error("Invalid relay route claim signature.");
+  }
+  const parsed = JSON.parse(base64UrlDecode(encodedPayload));
+  const host = assertExactRelayHost(parsed.host);
+  if (parsed.scope !== options.expectedScope) {
+    throw new Error("Relay route claim scope mismatch.");
+  }
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  if (Date.parse(parsed.expiresAt) <= now.getTime()) {
+    throw new Error("Relay route claim has expired.");
+  }
+  if (!parsed.agentId) {
+    throw new Error("Relay route claim requires an agentId.");
+  }
+  return { ...parsed, host };
+}
+function createRelayRouteRegistration(input) {
+  if (!authenticateRelayAgentToken({
+    agentToken: input.agentToken,
+    ...typeof input.authorizationHeader !== "undefined" ? { authorizationHeader: input.authorizationHeader } : {}
+  })) {
+    throw new Error("Relay route registration requires an authenticated local agent.");
+  }
+  const claim = verifyRelayRouteClaim(input.claimToken, input.signingSecret, {
+    expectedScope: input.expectedScope,
+    ...input.now ? { now: input.now } : {}
+  });
+  const target = assertRelayLocalTarget(input.target, input.targetPolicy);
+  const access = input.publicMode === true ? "public" : input.access ?? "private";
+  const passwordProtected = input.passwordProtected ?? false;
+  const authRequired = input.authRequired ?? false;
+  if (access === "public" && input.publicMode !== true) {
+    throw new Error("Relay public mode must be explicitly enabled.");
+  }
+  if (access === "private" && !passwordProtected && !authRequired) {
+    throw new Error("Private relay previews require password or auth.");
+  }
+  return {
+    host: claim.host,
+    scope: claim.scope,
+    agentId: claim.agentId,
+    expiresAt: claim.expiresAt,
+    target,
+    access,
+    passwordProtected,
+    authRequired,
+    limits: mergeLimits(input.limits)
+  };
+}
+function isRelayRouteActive(route, options) {
+  if (!options.agentConnected) return false;
+  return Date.parse(route.expiresAt) > (options.now ?? /* @__PURE__ */ new Date()).getTime();
+}
+function stripRelayForwardHeaders(headers) {
+  const stripped = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (typeof value === "undefined") continue;
+    const lowerName = name.toLowerCase();
+    if (HOP_BY_HOP_HEADERS.has(lowerName)) continue;
+    if (lowerName.startsWith("x-localghost-")) continue;
+    stripped[name] = value;
+  }
+  return stripped;
+}
+function redactRelayHeaders(headers) {
+  const redacted = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (typeof value === "undefined") continue;
+    redacted[name] = SENSITIVE_HEADERS.has(name.toLowerCase()) ? "[redacted]" : value;
+  }
+  return redacted;
+}
+function redactRelayLogUrl(input) {
+  const url = new URL(input, "http://localghost.invalid");
+  for (const key of [...url.searchParams.keys()]) {
+    if (TOKEN_QUERY_PATTERN.test(key)) {
+      url.searchParams.set(key, "[redacted]");
+    }
+  }
+  return input.startsWith("http://") || input.startsWith("https://") ? url.toString() : `${url.pathname}${url.search}`;
+}
+function renderRelayOfflineResponse() {
+  return {
+    status: 503,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store"
+    },
+    body: [
+      "<!doctype html>",
+      "<html>",
+      '<head><meta charset="utf-8"><title>Preview offline</title></head>',
+      "<body><h1>Preview offline</h1><p>The local agent is not connected. Try again later.</p></body>",
+      "</html>"
+    ].join("")
+  };
+}
+
 // src/routes.ts
+var ansi = {
+  cyan: "\x1B[36m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  reset: "\x1B[0m",
+  yellow: "\x1B[33m"
+};
+function colorize(value, color, enabled) {
+  return enabled ? `${color}${value}${ansi.reset}` : value;
+}
+function colorizeUrl(value, enabled) {
+  if (!enabled) return value;
+  return colorize(value.replace(/\*/g, `${ansi.yellow}*${ansi.cyan}`), ansi.cyan, enabled);
+}
 function getDomainRoutes(entries, options = {}) {
   const protocol = options.https === true ? "https" : "http";
   return [...entries].sort((left, right) => left.host.localeCompare(right.host) || left.port - right.port).map((entry) => ({
@@ -696,13 +1367,40 @@ function formatDomainRoutes(entries, options = {}) {
     ...routes.map((route) => `  ${route.url} -> ${route.upstream}`)
   ].join("\n");
 }
+function formatGhostTunnel(config, options = {}) {
+  if (!config.enabled) return null;
+  const color = options.color === true;
+  const label = options.label ?? "expected";
+  const labelColor = label === "running" ? ansi.green : ansi.dim;
+  const lines = [
+    "localghost ghost tunnel",
+    `  mode: ${config.mode}`
+  ];
+  const urls = config.displayUrls.length > 0 ? config.displayUrls : config.displayUrl ? [config.displayUrl] : [];
+  if (urls.length === 0) {
+    lines.push(`  ${label}: unavailable`);
+  } else if (urls.length === 1) {
+    lines.push(`  ${colorize(label, labelColor, color)}: ${colorizeUrl(urls[0], color)}`);
+  } else {
+    lines.push(`  ${colorize(label, labelColor, color)}:`);
+    for (const url of urls) {
+      lines.push(`    ${colorizeUrl(url, color)}`);
+    }
+  }
+  if (options.verbose) {
+    lines.push(`  domains: ${config.domains.length > 0 ? config.domains.join(", ") : "*"}`);
+    lines.push(`  access: ${config.requireAuth ? "auth required" : "app decides"}`);
+    lines.push(`  transport: ${config.requireHttps ? "https required" : "http allowed"}`);
+  }
+  return lines.join("\n");
+}
 
 // src/state.ts
 import { existsSync as existsSync5 } from "fs";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 var LOCALGHOST_STATE_FILE = "ops/local/localghost-state.json";
 function getLocalghostStatePath(cwd = process.cwd()) {
-  return join6(cwd, LOCALGHOST_STATE_FILE);
+  return join7(cwd, LOCALGHOST_STATE_FILE);
 }
 function readLocalghostState(cwd = process.cwd()) {
   const path = getLocalghostStatePath(cwd);
@@ -722,11 +1420,11 @@ function patchLocalghostState(cwd, patch) {
 }
 
 // src/update-check.ts
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname4, join as join7 } from "path";
+import { dirname as dirname4, join as join8 } from "path";
 var LOCALGHOST_PACKAGE_NAME = "@hamedb89/localghost";
-var LOCALGHOST_VERSION = "0.1.8";
+var LOCALGHOST_VERSION = "0.1.9";
 var UPDATE_CHECK_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var UPDATE_CHECK_NOTIFY_TTL_MS = 24 * 60 * 60 * 1e3;
 var UPDATE_CHECK_TIMEOUT_MS = 900;
@@ -738,13 +1436,13 @@ function isUpdateCheckDisabled(env = process.env) {
 }
 function getUpdateCheckCachePath(env = process.env) {
   if (env.LOCALGHOST_UPDATE_CHECK_CACHE) return env.LOCALGHOST_UPDATE_CHECK_CACHE;
-  const cacheRoot = env.XDG_CACHE_HOME || join7(homedir2(), ".cache");
-  return join7(cacheRoot, "localghost", "update-check.json");
+  const cacheRoot = env.XDG_CACHE_HOME || join8(homedir2(), ".cache");
+  return join8(cacheRoot, "localghost", "update-check.json");
 }
 function readCache(path = getUpdateCheckCachePath()) {
   if (!existsSync6(path)) return null;
   try {
-    return JSON.parse(readFileSync5(path, "utf8"));
+    return JSON.parse(readFileSync6(path, "utf8"));
   } catch {
     return null;
   }
@@ -888,6 +1586,10 @@ ${message}`);
   markUpdateNotified(result, cachePath);
 }
 export {
+  DEFAULT_RELAY_ALLOWED_TARGET_HOSTS,
+  DEFAULT_RELAY_BLOCKED_PORTS,
+  DEFAULT_RELAY_LIMITS,
+  DEFAULT_RELAY_TARGET_POLICY,
   LOCALGHOST_ACTIVITY_VERSION,
   LOCALGHOST_CONFIG_FILE,
   LOCALGHOST_PACKAGE_NAME,
@@ -896,20 +1598,35 @@ export {
   UPDATE_CHECK_CACHE_TTL_MS,
   UPDATE_CHECK_NOTIFY_TTL_MS,
   UPDATE_CHECK_TIMEOUT_MS,
+  assertExactRelayHost,
   assertLocalDevelopment,
+  assertRelayLocalTarget,
+  assertSecureGhostTunnelRequest,
+  authenticateRelayAgentToken,
   checkCaddy,
   checkForUpdate,
   compareVersions,
+  constructGhostTunnelHost,
+  constructGhostTunnelURL,
+  constructGhostTunnelUrl,
+  createRelayRouteRegistration,
   defineLocalghostConfig,
   detectPackageManager,
   findAvailablePort,
   findLocalMdnsHosts,
   formatDomainRoutes,
+  formatGhostTunnel,
   formatUpdateMessage,
   getCaddyfilePath,
   getConfigFileCandidates,
   getDevHostsPath,
   getDomainRoutes,
+  getGhostTunnelDefaultDisplayUrl,
+  getGhostTunnelDisplayUrl,
+  getGhostTunnelDisplayUrls,
+  getGhostTunnelEntryHost,
+  getGhostTunnelPreviewUrl,
+  getGhostTunnelWildcardHost,
   getLocalghostActivityPath,
   getLocalghostStatePath,
   getProductionEnvKeys,
@@ -922,35 +1639,48 @@ export {
   isPortAvailable,
   isProcessRunning,
   isProductionLike,
+  isRelayRouteActive,
   isUpdateCheckDisabled,
   listLocalghostRuns,
+  listLocalghostSetups,
   markUpdateNotified,
   maybeNotifyAboutUpdate,
   packageAddCommand,
   packageRunCommand,
   parseDevHosts,
+  parseGhostTunnelHost,
   patchLocalghostState,
   pruneLocalghostActivity,
   readDevHosts,
   readLocalghostActivity,
+  readLocalghostProjectConfig,
   readLocalghostState,
+  redactRelayHeaders,
+  redactRelayLogUrl,
   registerLocalghostRun,
+  registerLocalghostSetup,
   removeManagedBlock,
   removeSystemHosts,
   renderCaddyfile,
   renderHostsBlock,
+  renderRelayOfflineResponse,
   resolveDevHostsPath,
+  resolveGhostTunnelConfig,
   resolveLocalghostContext,
   runCaddy,
   runDoctor,
   sanitizeProjectName,
   shouldNotifyAboutUpdate,
+  signRelayRouteClaim,
   startCaddy,
+  stripRelayForwardHeaders,
   trustCaddy,
   unregisterLocalghostRun,
+  unregisterLocalghostSetup,
   updateSystemHosts,
   upsertManagedBlock,
   validateCaddyfile,
+  verifyRelayRouteClaim,
   writeCaddyfile,
   writeLocalghostActivity,
   writeLocalghostState