@hamedb89/localghost 0.1.15 → 0.3.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { D as DevHostEntry, R as ReadDevHostsOptions, a as ResolvedDevHostsPath, b as ConstructGhostTunnelUrlInput, c as GhostTunnelTransportOptions, d as GhostTunnelTransportConfig, e as GhostTunnelRoute, f as GhostTunnelConfig, C as ConfigPattern, G as GhostTunnelOptions } from './tunnel-BA52DD9e.js';
 export { g as GhostTunnelAdapterOptions, h as GhostTunnelAdapterProvider, i as GhostTunnelAdapterStrategy, j as GhostTunnelAdapterTransport, k as GhostTunnelDisplayDefaults, l as GhostTunnelDomainOptions, m as GhostTunnelMode, n as GhostTunnelNamespaceConfig, o as GhostTunnelNamespaceOptions, p as GhostTunnelNamespaceTag, q as GhostTunnelNamespaceValues, r as GhostTunnelPreviewOptions, s as GhostTunnelTransportKind, t as GhostTunnelTunnelStoreEnv, u as GhostTunnelTunnelStoreOptions, v as GhostTunnelTunnelStoreProvider, L as LOCALGHOST_CONFIG_FILE, w as assertSecureGhostTunnelRequest, x as constructGhostTunnelHost, y as constructGhostTunnelURL, z as constructGhostTunnelUrl, A as findLocalMdnsHosts, B as getConfigFileCandidates, E as getDevHostsPath, F as getGhostTunnelDefaultDisplayUrl, H as getGhostTunnelDisplayUrl, I as getGhostTunnelDisplayUrls, J as getGhostTunnelEntryHost, K as getGhostTunnelPreviewUrl, M as getGhostTunnelWildcardHost, N as getProjectName, O as parseDevHosts, P as parseGhostTunnelHost, Q as readDevHosts, S as resolveDevHostsPath, T as resolveGhostTunnelConfig, U as sanitizeProjectName } from './tunnel-BA52DD9e.js';
 import * as execa from 'execa';
+import { ChildProcess } from 'node:child_process';
 
 declare const LOCALGHOST_ACTIVITY_VERSION = 1;
 type LocalghostRunMode = "dev" | "run" | "vite";
@@ -15,6 +16,7 @@ type LocalghostRunRecord = {
     configPath?: string;
     caddyfilePath?: string;
     caddyPid?: number;
+    caddyPgid?: number;
     childPid?: number;
     childCommand?: string[];
     https?: boolean;
@@ -70,7 +72,7 @@ declare function unregisterLocalghostSetup(options: {
 declare function renderLocalghostBanner(): string;
 declare function renderCompactLocalghostBanner(): string;
 
-declare const LOCALGHOST_AGENT_GUIDE = "# Localghost agent guide\n\nLocalghost owns the local development proxy and the app process boundary.\n\n## Preferred repository setup\n\nFor a normal repository, use this package script:\n\n    \"dev\": \"localghost\"\n\nFor an explicit app command, keep the raw command separate:\n\n    \"dev\": \"localghost run -- vite\"\n    \"dev:raw\": \"vite\"\n\nUse `localghost dev` only when the Caddy proxy should run without starting the app.\n\n## Useful commands\n\n- `localghost`: detect and run the repository development command.\n- `localghost run -- <command>`: wrap an explicit app command.\n- `localghost dev`: run only the local Caddy proxy.\n- `localghost status --ready`: check project setup.\n- `localghost repair`: repair managed hosts and Caddy setup.\n- `localghost ps --json`: inspect Localghost-managed repositories, instances, and ports.\n- `localghost routes`: inspect hostname-to-port routing.\n- `localghost doctor`: check machine prerequisites.\n\n## Configuration\n\n- Commit repository defaults in `localghost.config.mjs`.\n- Keep hostname and requested-port routes in `.localghost`.\n- CLI flags override repository configuration for one invocation.\n- Localghost remembers active project and instance port assignments in user state under `~/.localghost`.\n- Do not edit the registry manually and do not start Caddy separately.\n\n## Port behavior\n\nLocalghost 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.\n";
+declare const LOCALGHOST_AGENT_GUIDE = "# Localghost agent guide\n\nLocalghost owns the local development proxy and the app process boundary.\n\n## Preferred repository setup\n\nFor a normal repository, use this package script:\n\n    \"dev\": \"localghost\"\n\nFor an explicit app command, keep the raw command separate:\n\n    \"dev\": \"localghost run -- vite\"\n    \"dev:raw\": \"vite\"\n\nUse `localghost dev` only when the Caddy proxy should run without starting the app.\n\n## Useful commands\n\n- `localghost`: detect and run the repository development command.\n- `localghost run -- <command>`: wrap an explicit app command.\n- `localghost dev`: run only the local Caddy proxy.\n- `localghost status --ready`: check project setup.\n- `localghost repair`: repair managed hosts and Caddy setup.\n- `localghost ps --json`: inspect Localghost-managed repositories, instances, and ports.\n- `localghost routes`: inspect hostname-to-port routing.\n- `localghost doctor`: check machine prerequisites, ports, and registry state.\n- `localghost repair --reallocate-port`: move an occupied project port to a stable available port.\n\n## Configuration\n\n- Commit repository defaults in `localghost.config.mjs`.\n- Keep hostname and requested-port routes in `.localghost`.\n- CLI flags override repository configuration for one invocation.\n- Localghost remembers active project and instance port assignments in user state under `~/.localghost`.\n- Do not edit the registry manually and do not start Caddy separately.\n\n## Port behavior\n\nLocalghost 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.\n";
 declare function formatLocalghostAgentGuide(format?: "text" | "json"): string;
 
 declare const LOCALGHOST_GHOST_TUNNEL_FILE = ".ghosttunnel";
@@ -338,6 +340,7 @@ declare function runCaddy(path: string): Promise<void>;
 declare function startCaddy(path: string): execa.ResultPromise<{
     cwd: string;
     stdio: "inherit" | "pipe";
+    detached: boolean;
 }>;
 declare function stopCaddyProcesses(pids: Iterable<number>, killProcess?: CaddyProcessKiller): CaddyProcessStopResult;
 declare function trustCaddy(path: string): Promise<void>;
@@ -465,9 +468,34 @@ type DoctorResult = {
         version?: string;
         installHint: string;
     };
+    ports: {
+        configured?: number;
+        available?: boolean;
+        registryPath: string;
+        staleLeases: Array<{
+            projectCwd: string;
+            instanceKey: string;
+            port: number;
+            pid: number;
+        }>;
+        duplicateAllocations: Array<{
+            port: number;
+            projects: string[];
+        }>;
+        currentAllocation?: {
+            projectCwd: string;
+            instanceKey: string;
+            port: number;
+        };
+    };
+};
+type DoctorOptions = {
+    cwd?: string;
+    configFiles?: string[];
+    configPattern?: ConfigPattern;
 };
 declare function checkCaddy(): Promise<DoctorResult["caddy"]>;
-declare function runDoctor(): Promise<DoctorResult>;
+declare function runDoctor(options?: DoctorOptions): Promise<DoctorResult>;
 
 type LocalghostEnvironment = NodeJS.ProcessEnv;
 declare function getProductionReason(env?: LocalghostEnvironment): "LOCALGHOST_ENV=production" | "NODE_ENV=production" | "VERCEL_ENV=production" | "NETLIFY=true and CONTEXT=production" | "CF_PAGES_BRANCH matches CF_PAGES_PRODUCTION_BRANCH" | null;
@@ -522,6 +550,11 @@ type FindAvailablePortOptions = {
 declare function isPortAvailable(port: number, host?: string): Promise<boolean>;
 declare function findAvailablePort(startPort: number, options?: FindAvailablePortOptions): Promise<number>;
 
+type ProcessSignal = NodeJS.Signals;
+type ProcessKiller = (pid: number, signal: ProcessSignal) => void;
+declare function signalManagedProcessPid(pid: number | undefined, signal: ProcessSignal, killProcess?: ProcessKiller): boolean;
+declare function signalManagedProcess(child: Pick<ChildProcess, "pid" | "kill" | "killed">, signal: ProcessSignal): boolean;
+
 declare const LOCALGHOST_REGISTRY_FILE = "registry.json";
 declare const LOCALGHOST_REGISTRY_LOCK_FILE = "registry.lock";
 type PortAvailabilityCheck = (port: number, host?: string) => boolean | Promise<boolean>;
@@ -577,6 +610,9 @@ type LocalghostRegistry = {
         instanceKey: string;
     }): Promise<boolean>;
     read(): Promise<LocalghostRegistryData>;
+    prune(): Promise<{
+        removedLeases: number;
+    }>;
 };
 declare function getLocalghostRegistryRoot(env?: NodeJS.ProcessEnv): string;
 declare function canonicalizeLocalghostProjectCwd(cwd?: string): string;
@@ -649,7 +685,7 @@ type CreateVercelGhostTunnelHandlerOptions = {
 declare function createVercelGhostTunnelHandler(options: CreateVercelGhostTunnelHandlerOptions): (request: VercelGhostTunnelRequestLike, response: VercelGhostTunnelResponseLike) => Promise<void>;
 
 declare const LOCALGHOST_PACKAGE_NAME = "@hamedb89/localghost";
-declare const LOCALGHOST_VERSION = "0.1.15";
+declare const LOCALGHOST_VERSION = "0.3.0";
 declare const UPDATE_CHECK_CACHE_TTL_MS: number;
 declare const UPDATE_CHECK_NOTIFY_TTL_MS: number;
 declare const UPDATE_CHECK_TIMEOUT_MS = 900;
@@ -686,4 +722,4 @@ declare function maybeNotifyAboutUpdate(options?: {
     disabled?: boolean;
 }): Promise<void>;
 
-export { type AcquireLocalghostPortOptions, type ActiveRelayRoute, type CaddyModeOptions, type CaddyProcessKiller, type CaddyProcessStopResult, ConfigPattern, type ConstructGhostTunnelIpUrlInput, ConstructGhostTunnelUrlInput, type CreateVercelGhostTunnelHandlerOptions, DEFAULT_GHOST_TUNNEL_IP_TRANSPORT_TTL_SECONDS, DEFAULT_GHOST_TUNNEL_RESPONSE_TTL_SECONDS, DEFAULT_GHOST_TUNNEL_TRANSPORT_QUERY_PARAM, DEFAULT_RELAY_ALLOWED_TARGET_HOSTS, DEFAULT_RELAY_BLOCKED_PORTS, DEFAULT_RELAY_LIMITS, DEFAULT_RELAY_TARGET_POLICY, type DetectedDevCommand, type DetectedDevService, DevHostEntry, type DoctorResult, type DomainRoute, type DomainRouteOptions, type FindAvailablePortOptions, type GhostTunnelAgent, type GhostTunnelAgentOptions, GhostTunnelConfig, type GhostTunnelHttpResponse, type GhostTunnelIpTransportClaim, GhostTunnelOptions, type GhostTunnelQueuedRequest, type GhostTunnelQueuedResponse, GhostTunnelRoute, type GhostTunnelRouteHeartbeat, type GhostTunnelStore, type GhostTunnelStoreEnv, GhostTunnelTransportConfig, GhostTunnelTransportOptions, type InitOptions, type InitResult, LOCALGHOST_ACTIVITY_VERSION, LOCALGHOST_AGENT_GUIDE, LOCALGHOST_GHOST_TUNNEL_FILE, LOCALGHOST_PACKAGE_NAME, LOCALGHOST_REGISTRY_FILE, LOCALGHOST_REGISTRY_LOCK_FILE, LOCALGHOST_STATE_FILE, LOCALGHOST_VERSION, type LocalghostActivity, type LocalghostContext, type LocalghostContextOptions, type LocalghostEnvironment, type LocalghostLease, type LocalghostPackageManager, type LocalghostProjectConfig, type LocalghostProjectConfigResult, type LocalghostRegistry, type LocalghostRegistryData, type LocalghostRegistryEntry, type LocalghostRegistryOptions, type LocalghostRunMode, type LocalghostRunRecord, type LocalghostServiceOptions, type LocalghostSetupRecord, type LocalghostState, type LocalghostStateAction, type PackageManager, type PortAvailabilityCheck, ReadDevHostsOptions, type ReadGhostTunnelOptions, type RedisGhostTunnelEnvResolution, type RedisGhostTunnelStoreOptions, type RegisterLocalghostRunInput, type RegisterLocalghostSetupInput, type RelayAccessMode, type RelayLimits, type RelayLocalTarget, type RelayOfflineResponse, type RelayProtocol, type RelayRouteClaim, type RelayRouteRegistrationInput, type RelayTargetPolicy, type RemoveSystemHostsResult, type ResolveGhostTunnelIpRedirectInput, type ResolveGhostTunnelRequestInput, ResolvedDevHostsPath, type ResolvedGhostTunnelIpRedirect, type ResolvedGhostTunnelRequest, type ServeGhostTunnelLocalRequestInput, type SignedGhostTunnelIpTransportClaim, type SignedRelayRouteClaim, UPDATE_CHECK_CACHE_TTL_MS, UPDATE_CHECK_NOTIFY_TTL_MS, UPDATE_CHECK_TIMEOUT_MS, type UpdateCheckCache, type UpdateCheckResult, type UpdateSystemHostsResult, type VercelGhostTunnelRequestLike, type VercelGhostTunnelResponseLike, type WriteLocalghostStateInput, assertExactRelayHost, assertLocalDevelopment, assertRelayLocalTarget, authenticateRelayAgentToken, canonicalizeLocalghostProjectCwd, checkCaddy, checkForUpdate, compareVersions, constructGhostTunnelIpUrl, createGhostTunnelQueuedRequest, createGhostTunnelRouteHeartbeat, createLocalghostRegistry, createMemoryGhostTunnelStore, createRedisGhostTunnelStore, createRedisGhostTunnelStoreFromEnv, createRelayRouteRegistration, createVercelGhostTunnelHandler, decodeGhostTunnelBody, defineLocalghostConfig, detectDevCommand, detectDevPackageManager, detectDevServices, detectPackageManager, encodeGhostTunnelBody, findAvailablePort, findGhostTunnelEntry, formatDetectedDevCommand, formatDetectedDevServices, formatDomainRoutes, formatGhostTunnel, formatLocalghostAgentGuide, formatUpdateMessage, getCaddyfilePath, getDomainRoutes, getGhostTunnelPath, getLocalghostActivityPath, getLocalghostRegistryRoot, getLocalghostStatePath, getProductionEnvKeys, getProductionReason, getSystemHostsPath, getUpdateCheckCachePath, initLocalghost, isNewerVersion, isPortAvailable, isProcessRunning, isProductionLike, isRelayRouteActive, isUpdateCheckDisabled, listGhostTunnelEntries, listLocalghostRuns, listLocalghostSetups, markUpdateNotified, maybeNotifyAboutUpdate, packageAddCommand, packageRunCommand, patchLocalghostState, pruneLocalghostActivity, readGhostTunnelEntries, readLocalghostActivity, readLocalghostProjectConfig, readLocalghostState, redactRelayHeaders, redactRelayLogUrl, registerLocalghostRun, registerLocalghostSetup, removeManagedBlock, removeSystemHosts, renderCaddyfile, renderCompactLocalghostBanner, renderGhostTunnelRelayOfflineResponse, renderGhostTunnelRouteMissingResponse, renderHostsBlock, renderLocalghostBanner, renderRelayOfflineResponse, resolveGhostTunnelIpRedirect, resolveGhostTunnelPath, resolveGhostTunnelRequest, resolveLocalghostContext, resolveRedisGhostTunnelEnv, runCaddy, runDoctor, serveGhostTunnelLocalRequest, shouldNotifyAboutUpdate, signGhostTunnelIpTransportClaim, signRelayRouteClaim, startCaddy, startGhostTunnelAgent, stopCaddyProcesses, stripRelayForwardHeaders, trustCaddy, unregisterLocalghostRun, unregisterLocalghostSetup, updateSystemHosts, upsertManagedBlock, validateCaddyfile, verifyGhostTunnelIpTransportClaim, verifyRelayRouteClaim, writeCaddyfile, writeLocalghostActivity, writeLocalghostState };
+export { type AcquireLocalghostPortOptions, type ActiveRelayRoute, type CaddyModeOptions, type CaddyProcessKiller, type CaddyProcessStopResult, ConfigPattern, type ConstructGhostTunnelIpUrlInput, ConstructGhostTunnelUrlInput, type CreateVercelGhostTunnelHandlerOptions, DEFAULT_GHOST_TUNNEL_IP_TRANSPORT_TTL_SECONDS, DEFAULT_GHOST_TUNNEL_RESPONSE_TTL_SECONDS, DEFAULT_GHOST_TUNNEL_TRANSPORT_QUERY_PARAM, DEFAULT_RELAY_ALLOWED_TARGET_HOSTS, DEFAULT_RELAY_BLOCKED_PORTS, DEFAULT_RELAY_LIMITS, DEFAULT_RELAY_TARGET_POLICY, type DetectedDevCommand, type DetectedDevService, DevHostEntry, type DoctorOptions, type DoctorResult, type DomainRoute, type DomainRouteOptions, type FindAvailablePortOptions, type GhostTunnelAgent, type GhostTunnelAgentOptions, GhostTunnelConfig, type GhostTunnelHttpResponse, type GhostTunnelIpTransportClaim, GhostTunnelOptions, type GhostTunnelQueuedRequest, type GhostTunnelQueuedResponse, GhostTunnelRoute, type GhostTunnelRouteHeartbeat, type GhostTunnelStore, type GhostTunnelStoreEnv, GhostTunnelTransportConfig, GhostTunnelTransportOptions, type InitOptions, type InitResult, LOCALGHOST_ACTIVITY_VERSION, LOCALGHOST_AGENT_GUIDE, LOCALGHOST_GHOST_TUNNEL_FILE, LOCALGHOST_PACKAGE_NAME, LOCALGHOST_REGISTRY_FILE, LOCALGHOST_REGISTRY_LOCK_FILE, LOCALGHOST_STATE_FILE, LOCALGHOST_VERSION, type LocalghostActivity, type LocalghostContext, type LocalghostContextOptions, type LocalghostEnvironment, type LocalghostLease, type LocalghostPackageManager, type LocalghostProjectConfig, type LocalghostProjectConfigResult, type LocalghostRegistry, type LocalghostRegistryData, type LocalghostRegistryEntry, type LocalghostRegistryOptions, type LocalghostRunMode, type LocalghostRunRecord, type LocalghostServiceOptions, type LocalghostSetupRecord, type LocalghostState, type LocalghostStateAction, type PackageManager, type PortAvailabilityCheck, ReadDevHostsOptions, type ReadGhostTunnelOptions, type RedisGhostTunnelEnvResolution, type RedisGhostTunnelStoreOptions, type RegisterLocalghostRunInput, type RegisterLocalghostSetupInput, type RelayAccessMode, type RelayLimits, type RelayLocalTarget, type RelayOfflineResponse, type RelayProtocol, type RelayRouteClaim, type RelayRouteRegistrationInput, type RelayTargetPolicy, type RemoveSystemHostsResult, type ResolveGhostTunnelIpRedirectInput, type ResolveGhostTunnelRequestInput, ResolvedDevHostsPath, type ResolvedGhostTunnelIpRedirect, type ResolvedGhostTunnelRequest, type ServeGhostTunnelLocalRequestInput, type SignedGhostTunnelIpTransportClaim, type SignedRelayRouteClaim, UPDATE_CHECK_CACHE_TTL_MS, UPDATE_CHECK_NOTIFY_TTL_MS, UPDATE_CHECK_TIMEOUT_MS, type UpdateCheckCache, type UpdateCheckResult, type UpdateSystemHostsResult, type VercelGhostTunnelRequestLike, type VercelGhostTunnelResponseLike, type WriteLocalghostStateInput, assertExactRelayHost, assertLocalDevelopment, assertRelayLocalTarget, authenticateRelayAgentToken, canonicalizeLocalghostProjectCwd, checkCaddy, checkForUpdate, compareVersions, constructGhostTunnelIpUrl, createGhostTunnelQueuedRequest, createGhostTunnelRouteHeartbeat, createLocalghostRegistry, createMemoryGhostTunnelStore, createRedisGhostTunnelStore, createRedisGhostTunnelStoreFromEnv, createRelayRouteRegistration, createVercelGhostTunnelHandler, decodeGhostTunnelBody, defineLocalghostConfig, detectDevCommand, detectDevPackageManager, detectDevServices, detectPackageManager, encodeGhostTunnelBody, findAvailablePort, findGhostTunnelEntry, formatDetectedDevCommand, formatDetectedDevServices, formatDomainRoutes, formatGhostTunnel, formatLocalghostAgentGuide, formatUpdateMessage, getCaddyfilePath, getDomainRoutes, getGhostTunnelPath, getLocalghostActivityPath, getLocalghostRegistryRoot, getLocalghostStatePath, getProductionEnvKeys, getProductionReason, getSystemHostsPath, getUpdateCheckCachePath, initLocalghost, isNewerVersion, isPortAvailable, isProcessRunning, isProductionLike, isRelayRouteActive, isUpdateCheckDisabled, listGhostTunnelEntries, listLocalghostRuns, listLocalghostSetups, markUpdateNotified, maybeNotifyAboutUpdate, packageAddCommand, packageRunCommand, patchLocalghostState, pruneLocalghostActivity, readGhostTunnelEntries, readLocalghostActivity, readLocalghostProjectConfig, readLocalghostState, redactRelayHeaders, redactRelayLogUrl, registerLocalghostRun, registerLocalghostSetup, removeManagedBlock, removeSystemHosts, renderCaddyfile, renderCompactLocalghostBanner, renderGhostTunnelRelayOfflineResponse, renderGhostTunnelRouteMissingResponse, renderHostsBlock, renderLocalghostBanner, renderRelayOfflineResponse, resolveGhostTunnelIpRedirect, resolveGhostTunnelPath, resolveGhostTunnelRequest, resolveLocalghostContext, resolveRedisGhostTunnelEnv, runCaddy, runDoctor, serveGhostTunnelLocalRequest, shouldNotifyAboutUpdate, signGhostTunnelIpTransportClaim, signRelayRouteClaim, signalManagedProcess, signalManagedProcessPid, startCaddy, startGhostTunnelAgent, stopCaddyProcesses, stripRelayForwardHeaders, trustCaddy, unregisterLocalghostRun, unregisterLocalghostSetup, updateSystemHosts, upsertManagedBlock, validateCaddyfile, verifyGhostTunnelIpTransportClaim, verifyRelayRouteClaim, writeCaddyfile, writeLocalghostActivity, writeLocalghostState };

package/dist/index.js

@@ -80,6 +80,7 @@ function registerLocalghostRun(input, path = getLocalghostActivityPath()) {
     ...input.configPath ? { configPath: input.configPath } : {},
     ...input.caddyfilePath ? { caddyfilePath: input.caddyfilePath } : {},
     ...input.caddyPid ? { caddyPid: input.caddyPid } : {},
+    ...input.caddyPgid ? { caddyPgid: input.caddyPgid } : {},
     ...input.childPid ? { childPid: input.childPid } : {},
     ...input.childCommand ? { childCommand: input.childCommand } : {},
     ...typeof input.https === "boolean" ? { https: input.https } : {},
@@ -301,7 +302,8 @@ Use \`localghost dev\` only when the Caddy proxy should run without starting the
 - \`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.
+- \`localghost doctor\`: check machine prerequisites, ports, and registry state.
+- \`localghost repair --reallocate-port\`: move an occupied project port to a stable available port.
 
 ## Configuration
 
@@ -1635,7 +1637,8 @@ async function runCaddy(path) {
 function startCaddy(path) {
   return execa("caddy", ["run", "--config", path], {
     cwd: dirname3(path),
-    stdio: caddyStdio()
+    stdio: caddyStdio(),
+    detached: process.platform !== "win32"
   });
 }
 function stopCaddyProcesses(pids, killProcess = (pid, signal) => process.kill(pid, signal)) {
@@ -1816,6 +1819,18 @@ function createLocalghostRegistry(options = {}) {
     lockPath,
     ownerToken,
     read: readRegistry,
+    async prune() {
+      const releaseLock = await lock();
+      try {
+        const registry = await readRegistry();
+        const before = registry.leases.length;
+        pruneRegistry(registry, now(), isRunning);
+        await writeRegistry(registry);
+        return { removedLeases: before - registry.leases.length };
+      } finally {
+        await releaseLock();
+      }
+    },
     async acquirePort(acquireOptions) {
       const projectCwd = canonicalizeLocalghostProjectCwd(acquireOptions.projectCwd ?? cwd);
       if (!acquireOptions.instanceKey) throw new Error("instanceKey is required");
@@ -2126,11 +2141,52 @@ async function checkCaddy() {
     };
   }
 }
-async function runDoctor() {
+async function runDoctor(options = {}) {
   const caddy = await checkCaddy();
+  const cwd = options.cwd ?? process.cwd();
+  const registry = createLocalghostRegistry({ cwd });
+  const data = await registry.read();
+  const now = Date.now();
+  const staleLeases = data.leases.filter((lease) => lease.expiresAt <= now || !isProcessRunning(lease.pid)).map(({ projectCwd, instanceKey, port, pid }) => ({ projectCwd, instanceKey, port, pid }));
+  const allocationsByPort = /* @__PURE__ */ new Map();
+  for (const allocation of data.allocations) {
+    const projects = allocationsByPort.get(allocation.port) ?? [];
+    projects.push(`${allocation.projectCwd}#${allocation.instanceKey}`);
+    allocationsByPort.set(allocation.port, projects);
+  }
+  const duplicateAllocations = [...allocationsByPort.entries()].filter(([, projects]) => projects.length > 1).map(([port, projects]) => ({ port, projects }));
+  let configured;
+  let available;
+  try {
+    const context = await resolveLocalghostContext({
+      cwd,
+      ...options.configFiles ? { configFiles: options.configFiles } : {},
+      ...options.configPattern ? { configPattern: options.configPattern } : {},
+      dynamicPort: false
+    });
+    configured = context.requestedPort;
+    available = await isPortAvailable(configured);
+  } catch {
+  }
+  const currentProjectCwd = canonicalizeLocalghostProjectCwd(cwd);
+  const currentAllocation = data.allocations.find((allocation) => allocation.projectCwd === currentProjectCwd);
   return {
-    ok: caddy.found,
-    caddy
+    ok: caddy.found && available !== false && staleLeases.length === 0 && duplicateAllocations.length === 0,
+    caddy,
+    ports: {
+      ...configured !== void 0 ? { configured } : {},
+      ...available !== void 0 ? { available } : {},
+      registryPath: registry.registryPath,
+      staleLeases,
+      duplicateAllocations,
+      ...currentAllocation ? {
+        currentAllocation: {
+          projectCwd: currentAllocation.projectCwd,
+          instanceKey: currentAllocation.instanceKey,
+          port: currentAllocation.port
+        }
+      } : {}
+    }
   };
 }
 
@@ -2471,6 +2527,25 @@ function initLocalghost(options = {}) {
   };
 }
 
+// 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;
+  try {
+    killProcess(process.platform === "win32" ? pid : -pid, signal);
+    return true;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ESRCH") return false;
+    throw error;
+  }
+}
+function signalManagedProcess(child, signal) {
+  if (process.platform === "win32") {
+    if (!child.killed) child.kill(signal);
+    return true;
+  }
+  return signalManagedProcessPid(child.pid, signal);
+}
+
 // src/routes.ts
 var ansi = {
   cyan: "\x1B[36m",
@@ -2790,7 +2865,7 @@ import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as rea
 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.15";
+var LOCALGHOST_VERSION = "0.3.0";
 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;
@@ -3077,6 +3152,8 @@ export {
   shouldNotifyAboutUpdate,
   signGhostTunnelIpTransportClaim,
   signRelayRouteClaim,
+  signalManagedProcess,
+  signalManagedProcessPid,
   startCaddy,
   startGhostTunnelAgent,
   stopCaddyProcesses,