@hamedb89/localghost 0.1.12 → 0.1.15

package/dist/index.js

@@ -265,10 +265,71 @@ function getProjectName(cwd = process.cwd()) {
   }
 }
 function sanitizeProjectName(value) {
-  const projectName = value.replace(/[^\w.-]+/g, "-").replace(/^-+|-+$/g, "");
+  const sanitized = value.replace(/[^\w.-]+/g, "-");
+  let start = 0;
+  let end = sanitized.length;
+  while (start < end && sanitized.charCodeAt(start) === 45) start += 1;
+  while (end > start && sanitized.charCodeAt(end - 1) === 45) end -= 1;
+  const projectName = sanitized.slice(start, end);
   return projectName || "app";
 }
 
+// src/guide.ts
+var LOCALGHOST_AGENT_GUIDE = `# Localghost agent guide
+
+Localghost owns the local development proxy and the app process boundary.
+
+## Preferred repository setup
+
+For a normal repository, use this package script:
+
+    "dev": "localghost"
+
+For an explicit app command, keep the raw command separate:
+
+    "dev": "localghost run -- vite"
+    "dev:raw": "vite"
+
+Use \`localghost dev\` only when the Caddy proxy should run without starting the app.
+
+## Useful commands
+
+- \`localghost\`: detect and run the repository development command.
+- \`localghost run -- <command>\`: wrap an explicit app command.
+- \`localghost dev\`: run only the local Caddy proxy.
+- \`localghost status --ready\`: check project setup.
+- \`localghost repair\`: repair managed hosts and Caddy setup.
+- \`localghost ps --json\`: inspect Localghost-managed repositories, instances, and ports.
+- \`localghost routes\`: inspect hostname-to-port routing.
+- \`localghost doctor\`: check machine prerequisites.
+
+## Configuration
+
+- Commit repository defaults in \`localghost.config.mjs\`.
+- Keep hostname and requested-port routes in \`.localghost\`.
+- CLI flags override repository configuration for one invocation.
+- Localghost remembers active project and instance port assignments in user state under \`~/.localghost\`.
+- Do not edit the registry manually and do not start Caddy separately.
+
+## Port behavior
+
+Localghost remembers ports by canonical repository path and instance key. Concurrent Localghost instances receive distinct ports. The operating-system bind check remains authoritative when another tool already owns a port.
+`;
+function formatLocalghostAgentGuide(format = "text") {
+  if (format === "json") {
+    return JSON.stringify({
+      preferredScript: "localghost",
+      explicitScript: "localghost run -- <command>",
+      proxyOnlyCommand: "localghost dev",
+      inspectionCommands: ["localghost status --ready", "localghost ps --json", "localghost routes", "localghost doctor"],
+      projectConfig: "localghost.config.mjs",
+      routeConfig: ".localghost",
+      userState: "~/.localghost"
+    }, null, 2);
+  }
+  return LOCALGHOST_AGENT_GUIDE;
+}
+
 // src/ghost-file.ts
 var LOCALGHOST_GHOST_TUNNEL_FILE = ".ghosttunnel";
 function toGhostTunnelOptions(options = {}) {
@@ -613,6 +674,11 @@ function parseJson(value) {
 function keyPart(value) {
   return value.toLowerCase().replace(/[^a-z0-9._:-]/g, "_");
 }
+function removeTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+  return value.slice(0, end);
+}
 var MemoryGhostTunnelStore = class {
   routes = /* @__PURE__ */ new Map();
   queues = /* @__PURE__ */ new Map();
@@ -668,7 +734,7 @@ var RedisGhostTunnelStore = class {
   namespace;
   fetchImpl;
   constructor(options) {
-    this.url = options.url.replace(/\/+$/, "");
+    this.url = removeTrailingSlashes(options.url);
     this.token = options.token;
     this.namespace = options.namespace ?? "localghost";
     this.fetchImpl = options.fetch ?? fetch;
@@ -756,11 +822,11 @@ function isStopped(signal, localSignal) {
 }
 function wait(ms, signal, localSignal) {
   if (isStopped(signal, localSignal)) return Promise.resolve();
-  return new Promise((resolve3) => {
-    const timeout = setTimeout(resolve3, ms);
+  return new Promise((resolve4) => {
+    const timeout = setTimeout(resolve4, ms);
     const stop = () => {
       clearTimeout(timeout);
-      resolve3();
+      resolve4();
     };
     signal?.addEventListener("abort", stop, { once: true });
     localSignal.addEventListener("abort", stop, { once: true });
@@ -1572,6 +1638,26 @@ function startCaddy(path) {
     stdio: caddyStdio()
   });
 }
+function stopCaddyProcesses(pids, killProcess = (pid, signal) => process.kill(pid, signal)) {
+  const result = {
+    stopped: [],
+    alreadyExited: [],
+    failed: []
+  };
+  for (const pid of new Set(pids)) {
+    try {
+      killProcess(pid, "SIGINT");
+      result.stopped.push(pid);
+    } catch (error) {
+      if (error instanceof Error && "code" in error && error.code === "ESRCH") {
+        result.alreadyExited.push(pid);
+      } else {
+        result.failed.push({ pid, error });
+      }
+    }
+  }
+  return result;
+}
 async function trustCaddy(path) {
   await execa("caddy", ["trust", "--config", path], {
     cwd: dirname3(path),
@@ -1581,19 +1667,19 @@ async function trustCaddy(path) {
 
 // src/context.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "fs";
-import { join as join4 } from "path";
+import { join as join5 } from "path";
 import { pathToFileURL } from "url";
 
 // src/port.ts
 import { createServer } from "net";
 async function isPortAvailable(port, host = "127.0.0.1") {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     const server = createServer();
     server.once("error", () => {
-      resolve3(false);
+      resolve4(false);
     });
     server.once("listening", () => {
-      server.close(() => resolve3(true));
+      server.close(() => resolve4(true));
     });
     server.listen(port, host);
   });
@@ -1610,6 +1696,176 @@ async function findAvailablePort(startPort, options = {}) {
   throw new Error(`No available port found from ${startPort} to ${startPort + maxAttempts - 1}.`);
 }
 
+// src/registry.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import { mkdir, open, readFile, rename, rm, stat, unlink, writeFile } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join4, normalize, resolve as resolve2 } from "path";
+var LOCALGHOST_REGISTRY_FILE = "registry.json";
+var LOCALGHOST_REGISTRY_LOCK_FILE = "registry.lock";
+function defaultProcessRunning(pid) {
+  if (pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function getLocalghostRegistryRoot(env = process.env) {
+  return resolve2(env.LOCALGHOST_HOME || join4(homedir2(), ".localghost"));
+}
+function canonicalizeLocalghostProjectCwd(cwd = process.cwd()) {
+  return normalize(resolve2(cwd));
+}
+function emptyRegistry() {
+  return { version: 1, allocations: [], leases: [] };
+}
+function leaseKey(projectCwd, instanceKey) {
+  return `${projectCwd}\0${instanceKey}`;
+}
+function validRegistry(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.version === 1 && Array.isArray(candidate.allocations) && Array.isArray(candidate.leases);
+}
+function pruneRegistry(registry, now, isRunning) {
+  registry.leases = registry.leases.filter((lease) => lease.expiresAt > now && isRunning(lease.pid));
+}
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return void 0;
+    return void 0;
+  }
+}
+function createLocalghostRegistry(options = {}) {
+  const root = resolve2(options.stateRoot ?? getLocalghostRegistryRoot());
+  const registryPath = join4(root, LOCALGHOST_REGISTRY_FILE);
+  const lockPath = join4(root, LOCALGHOST_REGISTRY_LOCK_FILE);
+  const cwd = canonicalizeLocalghostProjectCwd(options.cwd);
+  const now = options.now ?? Date.now;
+  const pid = options.pid ?? process.pid;
+  const ownerToken = options.ownerToken ?? randomUUID3();
+  const isRunning = options.isProcessRunning ?? defaultProcessRunning;
+  const availabilityCheck = options.availabilityCheck ?? isPortAvailable;
+  const lockTimeoutMs = options.lockTimeoutMs ?? 5e3;
+  const lockRetryMs = options.lockRetryMs ?? 25;
+  const lockStaleMs = options.lockStaleMs ?? 3e4;
+  async function readRegistry() {
+    const value = await readJson(registryPath);
+    return validRegistry(value) ? value : emptyRegistry();
+  }
+  async function writeRegistry(registry) {
+    await mkdir(root, { recursive: true });
+    const temporaryPath = join4(root, `.registry.${process.pid}.${randomUUID3()}.tmp`);
+    await writeFile(temporaryPath, `${JSON.stringify(registry, null, 2)}
+`, { mode: 384 });
+    await rename(temporaryPath, registryPath);
+  }
+  async function lock() {
+    await mkdir(root, { recursive: true });
+    const deadline = now() + lockTimeoutMs;
+    const token = randomUUID3();
+    while (true) {
+      try {
+        const handle = await open(lockPath, "wx", 384);
+        await handle.writeFile(`${JSON.stringify({ pid, createdAt: now(), token })}
+`);
+        await handle.close();
+        return async () => {
+          const current = await readJson(lockPath);
+          if (current?.token === token) await unlink(lockPath).catch(() => void 0);
+        };
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        const lockInfo = await readJson(lockPath);
+        let stale = false;
+        if (lockInfo && typeof lockInfo.pid === "number") {
+          stale = !isRunning(lockInfo.pid) && now() - lockInfo.createdAt >= 0;
+        } else {
+          try {
+            stale = now() - (await stat(lockPath)).mtimeMs > lockStaleMs;
+          } catch {
+            continue;
+          }
+        }
+        if (stale) {
+          await rm(lockPath, { force: true }).catch(() => void 0);
+          continue;
+        }
+        if (now() >= deadline) throw new Error(`Timed out waiting for Localghost registry lock: ${lockPath}`);
+        await new Promise((resolveDelay) => setTimeout(resolveDelay, lockRetryMs));
+      }
+    }
+  }
+  async function withLock(operation) {
+    const releaseLock = await lock();
+    try {
+      const registry = await readRegistry();
+      pruneRegistry(registry, now(), isRunning);
+      return await operation(registry);
+    } finally {
+      await releaseLock();
+    }
+  }
+  return {
+    root,
+    registryPath,
+    lockPath,
+    ownerToken,
+    read: readRegistry,
+    async acquirePort(acquireOptions) {
+      const projectCwd = canonicalizeLocalghostProjectCwd(acquireOptions.projectCwd ?? cwd);
+      if (!acquireOptions.instanceKey) throw new Error("instanceKey is required");
+      return withLock(async (registry) => {
+        const key = leaseKey(projectCwd, acquireOptions.instanceKey);
+        const existing = registry.allocations.find((entry2) => leaseKey(entry2.projectCwd, entry2.instanceKey) === key);
+        const reserved = new Set(acquireOptions.reservedPorts ?? []);
+        const activePorts = new Set(registry.leases.map((lease2) => lease2.port));
+        const port = existing?.port;
+        const ownsActiveLease = registry.leases.some((lease2) => lease2.port === port && leaseKey(lease2.projectCwd, lease2.instanceKey) === key && lease2.ownerToken === ownerToken);
+        const reusable = port !== void 0 && !reserved.has(port) && (!activePorts.has(port) || ownsActiveLease) && (ownsActiveLease || await availabilityCheck(port, acquireOptions.host));
+        let selectedPort = reusable ? port : void 0;
+        if (selectedPort === void 0) {
+          const startPort = acquireOptions.startPort ?? 3e3;
+          const maxAttempts = acquireOptions.maxAttempts ?? 50;
+          for (let offset = 0; offset < maxAttempts; offset += 1) {
+            const candidate = startPort + offset;
+            if (reserved.has(candidate) || activePorts.has(candidate)) continue;
+            if (await availabilityCheck(candidate, acquireOptions.host)) {
+              selectedPort = candidate;
+              break;
+            }
+          }
+          if (selectedPort === void 0) throw new Error(`No available registry port found from ${startPort} to ${startPort + maxAttempts - 1}.`);
+        }
+        const timestamp = now();
+        const entry = existing ?? { projectCwd, instanceKey: acquireOptions.instanceKey, port: selectedPort, updatedAt: timestamp };
+        entry.port = selectedPort;
+        entry.updatedAt = timestamp;
+        if (!existing) registry.allocations.push(entry);
+        registry.leases = registry.leases.filter((lease2) => leaseKey(lease2.projectCwd, lease2.instanceKey) !== key);
+        const lease = { projectCwd, instanceKey: acquireOptions.instanceKey, port: selectedPort, pid, acquiredAt: timestamp, expiresAt: timestamp + (acquireOptions.leaseTtlMs ?? 30 * 60 * 1e3), ownerToken };
+        registry.leases.push(lease);
+        await writeRegistry(registry);
+        return lease;
+      });
+    },
+    async releasePort(releaseOptions) {
+      const projectCwd = canonicalizeLocalghostProjectCwd(releaseOptions.projectCwd ?? cwd);
+      return withLock(async (registry) => {
+        const key = leaseKey(projectCwd, releaseOptions.instanceKey);
+        const before = registry.leases.length;
+        registry.leases = registry.leases.filter((lease) => leaseKey(lease.projectCwd, lease.instanceKey) !== key || lease.ownerToken !== ownerToken);
+        if (registry.leases.length !== before) await writeRegistry(registry);
+        return registry.leases.length !== before;
+      });
+    }
+  };
+}
+
 // src/context.ts
 var LOCALGHOST_PROJECT_CONFIG_FILES = [
   "localghost.config.mjs",
@@ -1636,7 +1892,7 @@ function envHttps() {
 }
 function getPackageName(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync4(join4(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync4(join5(cwd, "package.json"), "utf8"));
     return typeof pkg.name === "string" ? pkg.name : void 0;
   } catch {
     return void 0;
@@ -1722,7 +1978,24 @@ async function resolveLocalghostContext(options = {}) {
   const autoRepair = merged.autoRepair ?? 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;
+  let port = requestedPort;
+  let releasePort;
+  const reservePort = merged.reservePort ?? false;
+  const instanceKey = merged.instanceKey ?? "run";
+  if (reservePort && dynamicPort) {
+    const registry = createLocalghostRegistry({ cwd, ...merged.registryOwnerToken ? { ownerToken: merged.registryOwnerToken } : {} });
+    const lease = await registry.acquirePort({
+      projectCwd: cwd,
+      instanceKey,
+      startPort: requestedPort,
+      host: probeHost,
+      ...options.reservedPorts ? { reservedPorts: options.reservedPorts } : {}
+    });
+    port = lease.port;
+    releasePort = () => registry.releasePort({ projectCwd: cwd, instanceKey });
+  } else if (dynamicPort) {
+    port = await findAvailablePort(requestedPort, { host: probeHost });
+  }
   const wwwAlias = merged.wwwAlias ?? true;
   const entries = wwwAlias ? addDefaultWwwAliases(withRuntimePort(configEntries, requestedPort, port)) : withRuntimePort(configEntries, requestedPort, port);
   const hosts = uniqueHosts(entries);
@@ -1751,7 +2024,8 @@ async function resolveLocalghostContext(options = {}) {
     https: merged.https ?? envHttps() ?? false,
     wwwAlias,
     ghostTunnel,
-    ...projectConfig.path ? { projectConfigPath: projectConfig.path } : {}
+    ...projectConfig.path ? { projectConfigPath: projectConfig.path } : {},
+    ...releasePort ? { releasePort } : {}
   };
 }
 
@@ -1862,9 +2136,9 @@ async function runDoctor() {
 
 // src/command.ts
 import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
-import { isAbsolute, join as join5, relative, resolve as resolve2 } from "path";
+import { isAbsolute, join as join6, relative, resolve as resolve3 } from "path";
 function readPackageJson(cwd) {
-  const path = join5(cwd, "package.json");
+  const path = join6(cwd, "package.json");
   if (!existsSync4(path)) {
     throw new Error(`No package.json found in ${cwd}. Pass an explicit command with \`localghost run -- <command>\`.`);
   }
@@ -1879,9 +2153,9 @@ function detectDevPackageManager(cwd, packageManager) {
     const name = packageManager.split("@")[0];
     if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun") return name;
   }
-  if (existsSync4(join5(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync4(join5(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync4(join5(cwd, "bun.lock")) || existsSync4(join5(cwd, "bun.lockb"))) return "bun";
+  if (existsSync4(join6(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync4(join6(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync4(join6(cwd, "bun.lock")) || existsSync4(join6(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function scriptCommand(packageManager, script) {
@@ -1916,7 +2190,7 @@ function detectDevCommand(options = {}) {
     };
   }
   throw new Error([
-    `Could not detect a safe development command in ${join5(cwd, "package.json")}.`,
+    `Could not detect a safe development command in ${join6(cwd, "package.json")}.`,
     "Add a non-recursive dev or dev:raw script, configure command in localghost.config.mjs,",
     "or pass an explicit command with `localghost run -- <command>`."
   ].join(" "));
@@ -1927,7 +2201,7 @@ function formatDetectedDevCommand(detected) {
   return `${command} (${source})`;
 }
 function assertServicePath(root, serviceCwd, name) {
-  const cwd = resolve2(root, serviceCwd);
+  const cwd = resolve3(root, serviceCwd);
   const relativeCwd = relative(root, cwd);
   if (isAbsolute(relativeCwd) || relativeCwd === ".." || relativeCwd.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
     throw new Error(`Service ${name} cwd must stay inside the project root.`);
@@ -1998,7 +2272,7 @@ function getProductionEnvKeys() {
 // src/hosts-file.ts
 import { writeFileSync as writeFileSync3 } from "fs";
 import { tmpdir } from "os";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { execa as execa3 } from "execa";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -2041,7 +2315,7 @@ function removeManagedBlock(existing, projectName) {
 }
 async function writeSystemHostsFile(hostsPath, next, projectName) {
   const sanitizedProjectName = sanitizeProjectName(projectName);
-  const tempPath = join6(tmpdir(), `localghost-${sanitizedProjectName}-hosts`);
+  const tempPath = join7(tmpdir(), `localghost-${sanitizedProjectName}-hosts`);
   writeFileSync3(tempPath, next, "utf8");
   if (process.env.LOCALGHOST_HOSTS_PATH) {
     writeFileSync3(hostsPath, next, "utf8");
@@ -2079,20 +2353,23 @@ async function removeSystemHosts(projectName) {
 
 // src/init.ts
 import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 function detectPackageManager(cwd = process.cwd()) {
-  if (existsSync5(join7(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync5(join7(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync5(join8(cwd, "pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync5(join8(cwd, "yarn.lock"))) return "yarn";
+  if (existsSync5(join8(cwd, "bun.lock")) || existsSync5(join8(cwd, "bun.lockb"))) return "bun";
   return "npm";
 }
 function packageRunCommand(packageManager, script) {
   if (packageManager === "yarn") return `yarn ${script}`;
   if (packageManager === "pnpm") return `pnpm ${script}`;
+  if (packageManager === "bun") return `bun run ${script}`;
   return `npm run ${script}`;
 }
 function packageAddCommand(packageManager, packageName = "@hamedb89/localghost") {
   if (packageManager === "yarn") return `yarn add -D ${packageName}`;
   if (packageManager === "pnpm") return `pnpm add -D ${packageName}`;
+  if (packageManager === "bun") return `bun add -d ${packageName}`;
   return `npm install -D ${packageName}`;
 }
 function renderConfig(options) {
@@ -2160,7 +2437,7 @@ function initLocalghost(options = {}) {
   const apiPort = options.apiPort ?? 8787;
   const packageManager = options.packageManager ?? detectPackageManager(cwd);
   const configFile = options.configFile ?? LOCALGHOST_CONFIG_FILE;
-  const configPath = join7(cwd, configFile);
+  const configPath = join8(cwd, configFile);
   const configExists = existsSync5(configPath);
   if (configExists && !options.force) {
     return {
@@ -2177,7 +2454,7 @@ function initLocalghost(options = {}) {
     };
   }
   writeTextFile(configPath, renderConfig({ host, port, apiHost, apiPort }));
-  const packageJsonPath = join7(cwd, "package.json");
+  const packageJsonPath = join8(cwd, "package.json");
   const packageJsonChanged = options.writeScripts ? updatePackageScripts(packageJsonPath, configFile) : false;
   return {
     configPath,
@@ -2259,10 +2536,10 @@ function formatGhostTunnel(config, options = {}) {
 
 // src/state.ts
 import { existsSync as existsSync6 } from "fs";
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 var LOCALGHOST_STATE_FILE = "ops/local/localghost-state.json";
 function getLocalghostStatePath(cwd = process.cwd()) {
-  return join8(cwd, LOCALGHOST_STATE_FILE);
+  return join9(cwd, LOCALGHOST_STATE_FILE);
 }
 function readLocalghostState(cwd = process.cwd()) {
   const path = getLocalghostStatePath(cwd);
@@ -2410,7 +2687,7 @@ async function waitForTunnelResponse(input) {
       await input.store.cleanup(input.requestId);
       return response;
     }
-    await new Promise((resolve3) => setTimeout(resolve3, input.pollIntervalMs));
+    await new Promise((resolve4) => setTimeout(resolve4, input.pollIntervalMs));
   }
   return null;
 }
@@ -2510,10 +2787,10 @@ function createVercelGhostTunnelHandler(options) {
 
 // src/update-check.ts
 import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
-import { homedir as homedir2 } from "os";
-import { dirname as dirname4, join as join9 } from "path";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname4, join as join10 } from "path";
 var LOCALGHOST_PACKAGE_NAME = "@hamedb89/localghost";
-var LOCALGHOST_VERSION = "0.1.12";
+var LOCALGHOST_VERSION = "0.1.15";
 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;
@@ -2525,8 +2802,8 @@ 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 || join9(homedir2(), ".cache");
-  return join9(cacheRoot, "localghost", "update-check.json");
+  const cacheRoot = env.XDG_CACHE_HOME || join10(homedir3(), ".cache");
+  return join10(cacheRoot, "localghost", "update-check.json");
 }
 function readCache(path = getUpdateCheckCachePath()) {
   if (!existsSync7(path)) return null;
@@ -2578,7 +2855,7 @@ function isNewerVersion(candidate, current = LOCALGHOST_VERSION) {
   return Boolean(candidate && compareVersions(candidate, current) > 0);
 }
 async function fetchLatestVersion(packageName, timeoutMs) {
-  const encodedName = packageName.startsWith("@") ? `@${packageName.slice(1).replace("/", "%2f")}` : packageName;
+  const encodedName = packageName.startsWith("@") ? `@${packageName.slice(1).replaceAll("/", "%2f")}` : packageName;
   const response = await fetch(`https://registry.npmjs.org/${encodedName}`, {
     signal: AbortSignal.timeout(timeoutMs),
     headers: {
@@ -2683,9 +2960,12 @@ export {
   DEFAULT_RELAY_LIMITS,
   DEFAULT_RELAY_TARGET_POLICY,
   LOCALGHOST_ACTIVITY_VERSION,
+  LOCALGHOST_AGENT_GUIDE,
   LOCALGHOST_CONFIG_FILE,
   LOCALGHOST_GHOST_TUNNEL_FILE,
   LOCALGHOST_PACKAGE_NAME,
+  LOCALGHOST_REGISTRY_FILE,
+  LOCALGHOST_REGISTRY_LOCK_FILE,
   LOCALGHOST_STATE_FILE,
   LOCALGHOST_VERSION,
   UPDATE_CHECK_CACHE_TTL_MS,
@@ -2696,6 +2976,7 @@ export {
   assertRelayLocalTarget,
   assertSecureGhostTunnelRequest,
   authenticateRelayAgentToken,
+  canonicalizeLocalghostProjectCwd,
   checkCaddy,
   checkForUpdate,
   compareVersions,
@@ -2705,6 +2986,7 @@ export {
   constructGhostTunnelUrl,
   createGhostTunnelQueuedRequest,
   createGhostTunnelRouteHeartbeat,
+  createLocalghostRegistry,
   createMemoryGhostTunnelStore,
   createRedisGhostTunnelStore,
   createRedisGhostTunnelStoreFromEnv,
@@ -2724,6 +3006,7 @@ export {
   formatDetectedDevServices,
   formatDomainRoutes,
   formatGhostTunnel,
+  formatLocalghostAgentGuide,
   formatUpdateMessage,
   getCaddyfilePath,
   getConfigFileCandidates,
@@ -2737,6 +3020,7 @@ export {
   getGhostTunnelPreviewUrl,
   getGhostTunnelWildcardHost,
   getLocalghostActivityPath,
+  getLocalghostRegistryRoot,
   getLocalghostStatePath,
   getProductionEnvKeys,
   getProductionReason,
@@ -2795,6 +3079,7 @@ export {
   signRelayRouteClaim,
   startCaddy,
   startGhostTunnelAgent,
+  stopCaddyProcesses,
   stripRelayForwardHeaders,
   trustCaddy,
   unregisterLocalghostRun,