@hamedb89/localghost 0.4.1 → 0.6.1

package/dist/cli.js

@@ -487,13 +487,13 @@ import { pathToFileURL } from "url";
 // src/port.ts
 import { createServer } from "net";
 async function isPortAvailable(port, host = "127.0.0.1") {
-  return new Promise((resolve4) => {
+  return new Promise((resolve5) => {
     const server = createServer();
     server.once("error", () => {
-      resolve4(false);
+      resolve5(false);
     });
     server.once("listening", () => {
-      server.close(() => resolve4(true));
+      server.close(() => resolve5(true));
     });
     server.listen(port, host);
   });
@@ -546,6 +546,9 @@ function validRegistry(value) {
 function pruneRegistry(registry, now, isRunning) {
   registry.leases = registry.leases.filter((lease) => lease.expiresAt > now && isRunning(lease.pid));
 }
+function isTestSessionKey(instanceKey) {
+  return instanceKey.startsWith("test:");
+}
 async function readJson(path) {
   try {
     return JSON.parse(await readFile(path, "utf8"));
@@ -642,6 +645,37 @@ function createLocalghostRegistry(options = {}) {
         await releaseLock();
       }
     },
+    async pruneTestSessions() {
+      const releaseLock = await lock();
+      try {
+        const registry = await readRegistry();
+        const staleTestKeys = new Set(
+          registry.leases.filter((lease) => isTestSessionKey(lease.instanceKey) && (lease.expiresAt <= now() || !isRunning(lease.pid))).map((lease) => leaseKey(lease.projectCwd, lease.instanceKey))
+        );
+        const beforeLeases = registry.leases.length;
+        registry.leases = registry.leases.filter((lease) => !staleTestKeys.has(leaseKey(lease.projectCwd, lease.instanceKey)));
+        const activeKeys = new Set(registry.leases.map((lease) => leaseKey(lease.projectCwd, lease.instanceKey)));
+        const beforeAllocations = registry.allocations.length;
+        registry.allocations = registry.allocations.filter(
+          (allocation) => !isTestSessionKey(allocation.instanceKey) || activeKeys.has(leaseKey(allocation.projectCwd, allocation.instanceKey))
+        );
+        await writeRegistry(registry);
+        return {
+          removedLeases: beforeLeases - registry.leases.length,
+          removedAllocations: beforeAllocations - registry.allocations.length
+        };
+      } finally {
+        await releaseLock();
+      }
+    },
+    async reset() {
+      const releaseLock = await lock();
+      try {
+        await writeRegistry({ version: 1, allocations: [], leases: [] });
+      } finally {
+        await releaseLock();
+      }
+    },
     async acquirePort(acquireOptions) {
       const projectCwd = canonicalizeLocalghostProjectCwd(acquireOptions.projectCwd ?? cwd);
       if (!acquireOptions.instanceKey) throw new Error("instanceKey is required");
@@ -679,6 +713,18 @@ function createLocalghostRegistry(options = {}) {
         return lease;
       });
     },
+    async renewPort(renewOptions) {
+      const projectCwd = canonicalizeLocalghostProjectCwd(renewOptions.projectCwd ?? cwd);
+      return withLock(async (registry) => {
+        const lease = registry.leases.find(
+          (candidate) => candidate.projectCwd === projectCwd && candidate.instanceKey === renewOptions.instanceKey && candidate.ownerToken === ownerToken
+        );
+        if (!lease || lease.expiresAt <= now() || !isRunning(lease.pid)) return void 0;
+        lease.expiresAt = now() + (renewOptions.leaseTtlMs ?? 30 * 60 * 1e3);
+        await writeRegistry(registry);
+        return lease;
+      });
+    },
     async releasePort(releaseOptions) {
       const projectCwd = canonicalizeLocalghostProjectCwd(releaseOptions.projectCwd ?? cwd);
       return withLock(async (registry) => {
@@ -1558,11 +1604,11 @@ function isStopped(signal, localSignal) {
 }
 function wait(ms, signal, localSignal) {
   if (isStopped(signal, localSignal)) return Promise.resolve();
-  return new Promise((resolve4) => {
-    const timeout = setTimeout(resolve4, ms);
+  return new Promise((resolve5) => {
+    const timeout = setTimeout(resolve5, ms);
     const stop = () => {
       clearTimeout(timeout);
-      resolve4();
+      resolve5();
     };
     signal?.addEventListener("abort", stop, { once: true });
     localSignal.addEventListener("abort", stop, { once: true });
@@ -1784,13 +1830,23 @@ async function removeSystemHosts(projectName) {
 
 // src/init.ts
 import { existsSync as existsSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "fs";
-import { join as join8 } from "path";
+import { dirname as dirname4, join as join8, resolve as resolve4 } from "path";
 function detectPackageManager(cwd = process.cwd()) {
   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 isPnpmWorkspaceRoot(cwd = process.cwd()) {
+  const target = resolve4(cwd);
+  let current = target;
+  while (true) {
+    if (existsSync5(join8(current, "pnpm-workspace.yaml"))) return current === target;
+    const parent = dirname4(current);
+    if (parent === current) return false;
+    current = parent;
+  }
+}
 function packageRunCommand(packageManager, script) {
   if (packageManager === "yarn") return `yarn ${script}`;
   if (packageManager === "pnpm") return `pnpm ${script}`;
@@ -1910,6 +1966,59 @@ function initLocalghost(options = {}) {
   };
 }
 
+// src/test-session.ts
+async function createLocalghostTestSession(options) {
+  if (!options.instanceKey) throw new Error("instanceKey is required");
+  const registry = createLocalghostRegistry(options.cwd ? { cwd: options.cwd } : {});
+  const leases = [];
+  const ports = {};
+  const leaseTtlMs = options.leaseTtlMs ?? 30 * 60 * 1e3;
+  if (!Number.isFinite(leaseTtlMs) || leaseTtlMs < 1e3) throw new Error("leaseTtlMs must be at least 1000 milliseconds.");
+  try {
+    for (const [name, service] of Object.entries(options.services)) {
+      const lease = await registry.acquirePort({
+        ...options.cwd ? { projectCwd: options.cwd } : {},
+        instanceKey: `test:${options.instanceKey}:${name}`,
+        startPort: service.startPort,
+        ...service.maxAttempts !== void 0 ? { maxAttempts: service.maxAttempts } : {},
+        ...service.host !== void 0 ? { host: service.host } : {},
+        leaseTtlMs,
+        reservedPorts: Object.values(ports)
+      });
+      leases.push(lease);
+      ports[name] = lease.port;
+    }
+  } catch (error) {
+    await Promise.all(leases.map((lease) => registry.releasePort({ projectCwd: lease.projectCwd, instanceKey: lease.instanceKey })));
+    throw error;
+  }
+  let released = false;
+  const renew = async () => {
+    if (released) return;
+    await Promise.all(leases.map(async (lease) => {
+      const renewed = await registry.renewPort({ projectCwd: lease.projectCwd, instanceKey: lease.instanceKey, leaseTtlMs });
+      if (!renewed) throw new Error(`Localghost test lease expired: ${lease.instanceKey}`);
+    }));
+  };
+  return {
+    instanceKey: options.instanceKey,
+    ports,
+    leases,
+    renew,
+    startHeartbeat(intervalMs = Math.max(1e3, Math.floor(leaseTtlMs / 3))) {
+      if (!Number.isFinite(intervalMs) || intervalMs < 1e3) throw new Error("Heartbeat interval must be at least 1000 milliseconds.");
+      const timer = setInterval(() => void renew().catch(() => void 0), intervalMs);
+      timer.unref();
+      return timer;
+    },
+    async release() {
+      if (released) return;
+      released = true;
+      await Promise.all(leases.map((lease) => registry.releasePort({ projectCwd: lease.projectCwd, instanceKey: lease.instanceKey })));
+    }
+  };
+}
+
 // src/guide.ts
 var LOCALGHOST_AGENT_GUIDE = `# Localghost agent guide
 
@@ -2100,9 +2209,9 @@ function patchLocalghostState(cwd, patch) {
 // src/update-check.ts
 import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
 import { homedir as homedir3 } from "os";
-import { dirname as dirname4, join as join10 } from "path";
+import { dirname as dirname5, join as join10 } from "path";
 var LOCALGHOST_PACKAGE_NAME = "@hamedb89/localghost";
-var LOCALGHOST_VERSION = "0.4.1";
+var LOCALGHOST_VERSION = "0.6.1";
 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;
@@ -2127,7 +2236,7 @@ function readCache(path = getUpdateCheckCachePath()) {
 }
 function writeCache(cache, path = getUpdateCheckCachePath()) {
   try {
-    mkdirSync3(dirname4(path), { recursive: true });
+    mkdirSync3(dirname5(path), { recursive: true });
     writeFileSync5(path, `${JSON.stringify(cache, null, 2)}
 `, "utf8");
   } catch {
@@ -2270,7 +2379,7 @@ import { execa as execa4 } from "execa";
 
 // src/process.ts
 function signalManagedProcessPid(pid, signal, killProcess = (value, processSignal) => process.kill(value, processSignal)) {
-  if (typeof pid !== "number" || !Number.isInteger(pid) || pid < 1) return false;
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 1 || pid === process.pid) return false;
   try {
     killProcess(process.platform === "win32" ? pid : -pid, signal);
     return true;
@@ -2320,6 +2429,13 @@ function parsePort2(value) {
   }
   return port;
 }
+function parseCount(value) {
+  const count = Number.parseInt(value, 10);
+  if (!Number.isInteger(count) || count < 1 || count > 100) {
+    throw new InvalidArgumentError("Count must be a number between 1 and 100.");
+  }
+  return count;
+}
 function parsePackageManager(value) {
   if (value === "npm" || value === "yarn" || value === "pnpm" || value === "bun") return value;
   throw new InvalidArgumentError("Package manager must be npm, pnpm, yarn, or bun.");
@@ -2496,7 +2612,7 @@ async function runSetupFromReadiness(cwd, https, readiness) {
   });
 }
 function wait2(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 async function runTrust(cwd, caddyfilePath) {
   await wait2(350);
@@ -2527,6 +2643,69 @@ async function maybeTrustCaddy(options) {
   }
   await runTrust(options.cwd, options.caddyfilePath);
 }
+async function readPortStatuses() {
+  const registry = createLocalghostRegistry();
+  const data = await registry.read();
+  const rows = /* @__PURE__ */ new Map();
+  const now = Date.now();
+  for (const allocation of data.allocations) {
+    rows.set(`${allocation.projectCwd}\0${allocation.instanceKey}`, {
+      port: allocation.port,
+      state: "available",
+      projectCwd: allocation.projectCwd,
+      instanceKey: allocation.instanceKey,
+      available: true
+    });
+  }
+  for (const lease of data.leases) {
+    const running = lease.expiresAt > now && isProcessRunning(lease.pid);
+    const key = `${lease.projectCwd}\0${lease.instanceKey}`;
+    rows.set(key, {
+      port: lease.port,
+      state: running ? "active" : "stale",
+      projectCwd: lease.projectCwd,
+      instanceKey: lease.instanceKey,
+      available: false,
+      pid: lease.pid,
+      processRunning: isProcessRunning(lease.pid),
+      expiresAt: lease.expiresAt
+    });
+  }
+  const activity = readLocalghostActivity();
+  for (const run of activity.runs) {
+    const ports = [...new Set(run.entries.map((entry) => entry.port))];
+    for (const port of ports) {
+      const key = `${run.cwd}\0activity:${run.id}:${port}`;
+      if (!rows.has(key)) {
+        const running = isProcessRunning(run.pid);
+        rows.set(key, {
+          port,
+          state: running ? "active" : "stale",
+          projectCwd: run.cwd,
+          instanceKey: `activity:${run.mode}`,
+          available: false,
+          pid: run.pid,
+          processRunning: running
+        });
+      }
+    }
+  }
+  const statuses = await Promise.all([...rows.values()].map(async (row) => {
+    if (row.state === "active" || row.state === "stale") {
+      return { ...row, available: await isPortAvailable(row.port) };
+    }
+    const available = await isPortAvailable(row.port);
+    return { ...row, available, state: available ? "available" : "occupied" };
+  }));
+  return { registryPath: registry.registryPath, statuses };
+}
+async function findFreePorts(startPort, count) {
+  const ports = [];
+  for (let port = startPort; port <= 65535 && ports.length < count; port += 1) {
+    if (await isPortAvailable(port)) ports.push(port);
+  }
+  return ports;
+}
 function maybePid(pid) {
   return typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? pid : void 0;
 }
@@ -2552,10 +2731,13 @@ function registerSignalShutdown(stop) {
   };
   process.once("SIGINT", request);
   process.once("SIGTERM", request);
-  return () => {
-    process.off("SIGINT", request);
-    process.off("SIGTERM", request);
-    request();
+  return {
+    wasRequested: () => requested,
+    finish: () => {
+      process.off("SIGINT", request);
+      process.off("SIGTERM", request);
+      if (!requested) stop();
+    }
   };
 }
 async function resolveServiceRuntimeEntries(services, dynamicPort, projectCwd) {
@@ -2607,11 +2789,22 @@ async function waitForPortsToBeAvailable(entries, timeoutMs = 1e4) {
   const deadline = Date.now() + timeoutMs;
   const ports = [...new Set(entries.map((entry) => entry.port))];
   while (Date.now() < deadline) {
-    const availability = await Promise.all(ports.map((port) => isPortAvailable(port)));
-    if (availability.every(Boolean)) return true;
+    const availability2 = await Promise.all(ports.map((port) => isPortAvailable(port)));
+    if (availability2.every(Boolean)) return { available: true, blocked: [] };
     await wait2(50);
   }
-  return false;
+  const availability = await Promise.all(entries.map(async (entry) => ({
+    entry,
+    available: await isPortAvailable(entry.port)
+  })));
+  const blocked = availability.filter(({ available }) => !available).map(({ entry }) => entry);
+  return { available: blocked.length === 0, blocked };
+}
+function formatBlockedPorts(entries) {
+  return [...new Map(entries.map((entry) => [
+    `${entry.host}:${entry.port}`,
+    `${entry.host} (port ${entry.port})`
+  ])).values()].join(", ");
 }
 async function waitForProcessShutdown(processes, forceStop, timeoutMs = 1e4) {
   const settled = Promise.allSettled(processes);
@@ -2702,7 +2895,7 @@ async function runDetectedServices(options) {
       }
       signalManagedProcess(caddy, signal);
     };
-    const finishShutdown = registerSignalShutdown(() => stopManaged("SIGINT"));
+    const shutdown = registerSignalShutdown(() => stopManaged("SIGINT"));
     try {
       const ready = await Promise.race([
         waitForServicePorts(entries),
@@ -2714,15 +2907,18 @@ async function runDetectedServices(options) {
       }
       await processExit;
     } finally {
-      finishShutdown();
+      shutdown.finish();
       await waitForProcessShutdown(
         [caddyExit, ...children],
         stopManaged
       );
-      if (!await waitForPortsToBeAvailable(entries)) {
-        console.warn("Localghost: timed out waiting for service ports to be released.");
+      const drained = await waitForPortsToBeAvailable(entries);
+      if (!drained.available && !shutdown.wasRequested()) {
+        console.warn(`Localghost: timed out waiting for service ports to be released: ${formatBlockedPorts(drained.blocked)}.`);
         stopManaged("SIGTERM");
-        if (!await waitForPortsToBeAvailable(entries, 2e3)) {
+        const terminated = await waitForPortsToBeAvailable(entries, 2e3);
+        if (!terminated.available) {
+          console.warn(`Localghost: service ports still occupied after termination: ${formatBlockedPorts(terminated.blocked)}.`);
           stopManaged("SIGKILL");
         }
       }
@@ -2908,6 +3104,9 @@ program.command("upgrade").description("Install or update Localghost in the curr
   const packageManager = detectPackageManager(options.cwd);
   const packageName = "@hamedb89/localghost@latest";
   const args = packageManager === "yarn" ? ["add", "--dev", packageName] : packageManager === "pnpm" ? ["add", "--save-dev", packageName] : packageManager === "bun" ? ["add", "--dev", packageName] : ["install", "--save-dev", packageName];
+  if (packageManager === "pnpm" && isPnpmWorkspaceRoot(options.cwd)) {
+    args.splice(1, 0, "--workspace-root");
+  }
   console.log(`Upgrading ${packageName} with ${packageManager}...`);
   await execa4(packageManager, args, { cwd: options.cwd, stdio: "inherit" });
   console.log(`Localghost is upgraded in ${options.cwd}.`);
@@ -3097,7 +3296,77 @@ program.command("teardown").description("Remove Localghost's managed /etc/hosts
   unregisterLocalghostSetup({ cwd: options.cwd, projectName });
   console.log(`State ${statePath}`);
 });
-program.command("status").description("Print Localghost's project-local state file").option("--project <name>", "Managed /etc/hosts block name").option("--cwd <path>", "Project directory", process.cwd()).option("--config <file>", "Config file to look for. Can be repeated.", collect, []).option("--config-pattern <regex>", "Regex for config filenames in the project root").option("--ready", "Exit non-zero when setup is missing or stale").option("--https", "Check setup readiness for HTTPS mode").option("--ssl", "Alias for --https").option("--json", "Print raw JSON").action(async (options) => {
+program.command("ports").description("Manage Localghost port registry state").addCommand(new Command("prune").description("Remove expired or dead port leases").option("--cwd <path>", "Project directory", process.cwd()).option("--test-only", "Remove only stale test-session leases and records").option("--json", "Print raw JSON").action(async (options) => {
+  const result = options.testOnly ? await createLocalghostRegistry({ cwd: options.cwd }).pruneTestSessions() : await createLocalghostRegistry({ cwd: options.cwd }).prune();
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else console.log(`Pruned ${result.removedLeases} stale registry lease${result.removedLeases === 1 ? "" : "s"}${"removedAllocations" in result ? ` and ${result.removedAllocations} test allocation${result.removedAllocations === 1 ? "" : "s"}` : ""}.`);
+})).addCommand(new Command("reset").description("Clear all remembered allocations and leases").option("--cwd <path>", "Project directory", process.cwd()).option("--yes", "Confirm the destructive registry reset").action(async (options) => {
+  if (!options.yes) throw new Error("Resetting the port registry is destructive. Re-run with --yes.");
+  await createLocalghostRegistry({ cwd: options.cwd }).reset();
+  console.log("Localghost port registry reset.");
+}));
+program.command("test").description("Run a test command with an isolated Localghost port").option("--cwd <path>", "Project directory", process.cwd()).option("--instance <name>", "Parallel test instance name", String(process.pid)).option("--port <number>", "Initial test port", parsePort2, 5173).option("--lease-ttl <milliseconds>", "Lease lifetime before heartbeat renewal", Number, 30 * 60 * 1e3).argument("<command...>", "Command to run after --").action(async (command, options) => {
+  const [binary, ...args] = command;
+  if (!binary) throw new Error("Missing command. Use: localghost test -- <command>");
+  const session = await createLocalghostTestSession({
+    cwd: options.cwd,
+    instanceKey: options.instance,
+    leaseTtlMs: options.leaseTtl,
+    services: { default: { startPort: options.port } }
+  });
+  const heartbeat = session.startHeartbeat();
+  const child = execa4(binary, args, {
+    cwd: options.cwd,
+    stdio: "inherit",
+    detached: process.platform !== "win32",
+    env: {
+      ...process.env,
+      LOCALGHOST_INSTANCE: options.instance,
+      LOCALGHOST_PORT: String(session.ports.default),
+      LOCALGHOST_DYNAMIC_PORT: "1",
+      VITE_PORT: String(session.ports.default)
+    }
+  });
+  const stop = (signal) => signalManagedProcess(child, signal);
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+  try {
+    await child;
+  } finally {
+    process.off("SIGINT", stop);
+    process.off("SIGTERM", stop);
+    clearInterval(heartbeat);
+    await session.release();
+  }
+});
+program.command("status").description("Print Localghost's project-local state file").option("--project <name>", "Managed /etc/hosts block name").option("--cwd <path>", "Project directory", process.cwd()).option("--config <file>", "Config file to look for. Can be repeated.", collect, []).option("--config-pattern <regex>", "Regex for config filenames in the project root").option("--ready", "Exit non-zero when setup is missing or stale").option("--https", "Check setup readiness for HTTPS mode").option("--ssl", "Alias for --https").option("--ports", "List Localghost-managed and active ports").option("--from <port>", "First port to probe for free ports", parsePort2, 3e3).option("--count <number>", "Number of free ports to find", parseCount, 5).option("--json", "Print raw JSON").action(async (options) => {
+  if (options.ports) {
+    const [{ registryPath, statuses }, freePorts] = await Promise.all([
+      readPortStatuses(),
+      findFreePorts(options.from, options.count)
+    ]);
+    const result = {
+      registryPath,
+      ports: statuses.sort((left, right) => left.port - right.port),
+      free: { from: options.from, count: options.count, ports: freePorts }
+    };
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(`Registry: ${registryPath}`);
+    if (result.ports.length === 0) {
+      console.log("No Localghost ports are currently recorded.");
+    } else {
+      console.log("Port  State      Project / instance");
+      for (const port of result.ports) {
+        const owner = `${port.projectCwd} / ${port.instanceKey}`;
+        console.log(`${String(port.port).padEnd(5)} ${port.state.padEnd(10)} ${owner}`);
+      }
+    }
+    console.log(`Free ports from ${options.from}: ${freePorts.join(", ") || "none found"}`);
+    return;
+  }
   const state = readLocalghostState(options.cwd);
   const statePath = getLocalghostStatePath(options.cwd);
   const context = await resolveLocalghostContext({ ...contextOptionsFromCli(options), dynamicPort: false });
@@ -3230,107 +3499,113 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
     ...typeof options.dynamicPort === "boolean" ? { dynamicPort: options.dynamicPort } : {},
     ...typeof options.autoRepair === "boolean" ? { autoRepair: options.autoRepair } : {}
   });
-  const https = context.https;
-  const readiness = getSetupReadiness({
-    ...options,
-    https,
-    ignoreCaddyfile: true,
-    entries: context.entries,
-    configPath: context.configPath,
-    projectName: context.projectName
-  });
-  if (!readiness.ready) {
-    if (!options.setup && !context.autoRepair) {
-      throw new Error(
-        [
-          "Localghost setup is missing or stale.",
-          ...readiness.reasons.map((reason) => `- ${reason}`),
-          `Run: ${readiness.setupCommand}`,
-          "Automatic repair is disabled. Rerun without --auto-repair=no or run localghost repair."
-        ].join("\n")
-      );
-    }
-    console.log("Localghost setup is stale; repairing it now.");
-    await runSetupFromReadiness(options.cwd, https, readiness);
-    console.log(`Repair complete. Setup state: ${getLocalghostStatePath(options.cwd)}`);
-  }
-  if (context.dynamicPort && context.port !== context.requestedPort) {
-    console.log(`Port ${context.requestedPort} is busy; using ${context.port}.`);
-  }
-  warnAboutLocalMdns(context.entries);
-  logDomainRoutes(context.entries, { https, ghostTunnel: context.ghostTunnel });
-  const caddyfile = await writeCaddyfile(context.entries, options.cwd, { https });
-  await validateCaddyfile(caddyfile);
-  const caddy = startCaddy(caddyfile);
-  const caddyExit = caddy.catch((error) => {
-    if (!caddy.killed) throw error;
-  });
   try {
-    await maybeTrustCaddy({
-      cwd: options.cwd,
+    const https = context.https;
+    const readiness = getSetupReadiness({
+      ...options,
       https,
-      caddyfilePath: caddyfile,
-      ...typeof options.trust === "boolean" ? { trust: options.trust } : {}
+      ignoreCaddyfile: true,
+      entries: context.entries,
+      configPath: context.configPath,
+      projectName: context.projectName
     });
-  } catch (error) {
-    signalManagedProcess(caddy, "SIGINT");
-    throw error;
-  }
-  const [binary, ...args] = command;
-  if (!binary) {
-    throw new Error("Missing command. Use: localghost run -- vite");
-  }
-  const child = execa4(binary, args, {
-    cwd: options.cwd,
-    stdio: "inherit",
-    detached: process.platform !== "win32",
-    env: {
-      ...process.env,
-      LOCALGHOST_PORT: String(context.port),
-      LOCALGHOST_DYNAMIC_PORT: context.dynamicPort ? "1" : "0",
-      VITE_PORT: String(context.port)
+    if (!readiness.ready) {
+      if (!options.setup && !context.autoRepair) {
+        throw new Error(
+          [
+            "Localghost setup is missing or stale.",
+            ...readiness.reasons.map((reason) => `- ${reason}`),
+            `Run: ${readiness.setupCommand}`,
+            "Automatic repair is disabled. Rerun without --auto-repair=no or run localghost repair."
+          ].join("\n")
+        );
+      }
+      console.log("Localghost setup is stale; repairing it now.");
+      await runSetupFromReadiness(options.cwd, https, readiness);
+      console.log(`Repair complete. Setup state: ${getLocalghostStatePath(options.cwd)}`);
     }
-  });
-  const caddyPid = maybePid(caddy.pid);
-  const childPid = maybePid(child.pid);
-  const runRecord = registerLocalghostRun({
-    mode: "run",
-    cwd: context.cwd,
-    projectName: context.projectName,
-    configPath: context.configPath,
-    caddyfilePath: caddyfile,
-    ...caddyPid ? { caddyPid } : {},
-    ...caddyPid ? { caddyPgid: caddyPid } : {},
-    ...childPid ? { childPid } : {},
-    childCommand: command,
-    https,
-    requestedPort: context.requestedPort,
-    port: context.port,
-    dynamicPort: context.dynamicPort,
-    entries: context.entries
-  });
-  const cleanupRun = registerCleanup(runRecord.id);
-  const stopManaged = (signal) => {
-    signalManagedProcess(child, signal);
-    signalManagedProcess(caddy, signal);
-  };
-  const finishShutdown = registerSignalShutdown(() => stopManaged("SIGINT"));
-  try {
-    await Promise.race([child, caddyExit]);
-  } finally {
-    finishShutdown();
-    await waitForProcessShutdown(
-      [child, caddyExit],
-      stopManaged
-    );
-    if (!await waitForPortsToBeAvailable(context.entries)) {
-      console.warn("Localghost: timed out waiting for service ports to be released.");
-      stopManaged("SIGTERM");
-      if (!await waitForPortsToBeAvailable(context.entries, 2e3)) {
-        stopManaged("SIGKILL");
+    if (context.dynamicPort && context.port !== context.requestedPort) {
+      console.log(`Port ${context.requestedPort} is busy; using ${context.port}.`);
+    }
+    warnAboutLocalMdns(context.entries);
+    logDomainRoutes(context.entries, { https, ghostTunnel: context.ghostTunnel });
+    const caddyfile = await writeCaddyfile(context.entries, options.cwd, { https });
+    await validateCaddyfile(caddyfile);
+    const caddy = startCaddy(caddyfile);
+    const caddyExit = caddy.catch((error) => {
+      if (!caddy.killed) throw error;
+    });
+    try {
+      await maybeTrustCaddy({
+        cwd: options.cwd,
+        https,
+        caddyfilePath: caddyfile,
+        ...typeof options.trust === "boolean" ? { trust: options.trust } : {}
+      });
+    } catch (error) {
+      signalManagedProcess(caddy, "SIGINT");
+      throw error;
+    }
+    const [binary, ...args] = command;
+    if (!binary) {
+      throw new Error("Missing command. Use: localghost run -- vite");
+    }
+    const child = execa4(binary, args, {
+      cwd: options.cwd,
+      stdio: "inherit",
+      detached: process.platform !== "win32",
+      env: {
+        ...process.env,
+        LOCALGHOST_PORT: String(context.port),
+        LOCALGHOST_DYNAMIC_PORT: context.dynamicPort ? "1" : "0",
+        VITE_PORT: String(context.port)
+      }
+    });
+    const caddyPid = maybePid(caddy.pid);
+    const childPid = maybePid(child.pid);
+    const runRecord = registerLocalghostRun({
+      mode: "run",
+      cwd: context.cwd,
+      projectName: context.projectName,
+      configPath: context.configPath,
+      caddyfilePath: caddyfile,
+      ...caddyPid ? { caddyPid } : {},
+      ...caddyPid ? { caddyPgid: caddyPid } : {},
+      ...childPid ? { childPid } : {},
+      childCommand: command,
+      https,
+      requestedPort: context.requestedPort,
+      port: context.port,
+      dynamicPort: context.dynamicPort,
+      entries: context.entries
+    });
+    const cleanupRun = registerCleanup(runRecord.id);
+    const stopManaged = (signal) => {
+      signalManagedProcess(child, signal);
+      signalManagedProcess(caddy, signal);
+    };
+    const shutdown = registerSignalShutdown(() => stopManaged("SIGINT"));
+    try {
+      await Promise.race([child, caddyExit]);
+    } finally {
+      shutdown.finish();
+      await waitForProcessShutdown(
+        [child, caddyExit],
+        stopManaged
+      );
+      const drained = await waitForPortsToBeAvailable(context.entries);
+      if (!drained.available && !shutdown.wasRequested()) {
+        console.warn(`Localghost: timed out waiting for service ports to be released: ${formatBlockedPorts(drained.blocked)}.`);
+        stopManaged("SIGTERM");
+        const terminated = await waitForPortsToBeAvailable(context.entries, 2e3);
+        if (!terminated.available) {
+          console.warn(`Localghost: service ports still occupied after termination: ${formatBlockedPorts(terminated.blocked)}.`);
+          stopManaged("SIGKILL");
+        }
       }
+      cleanupRun();
     }
-    cleanupRun();
+  } finally {
     await context.releasePort?.();
   }
 });