@hamedb89/localghost 0.1.13 → 0.1.15

package/dist/index.d.ts

@@ -70,6 +70,9 @@ 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 function formatLocalghostAgentGuide(format?: "text" | "json"): string;
+
 declare const LOCALGHOST_GHOST_TUNNEL_FILE = ".ghosttunnel";
 type ReadGhostTunnelOptions = ReadDevHostsOptions;
 declare function resolveGhostTunnelPath(options?: ReadGhostTunnelOptions | string): ResolvedDevHostsPath;
@@ -318,6 +321,15 @@ declare function resolveGhostTunnelIpRedirect(input: ResolveGhostTunnelIpRedirec
 type CaddyModeOptions = {
     https?: boolean;
 };
+type CaddyProcessStopResult = {
+    stopped: number[];
+    alreadyExited: number[];
+    failed: Array<{
+        pid: number;
+        error: unknown;
+    }>;
+};
+type CaddyProcessKiller = (pid: number, signal: NodeJS.Signals) => void;
 declare function getCaddyfilePath(cwd?: string): string;
 declare function renderCaddyfile(entries: DevHostEntry[], options?: CaddyModeOptions): string;
 declare function writeCaddyfile(entries: DevHostEntry[], cwd?: string, options?: CaddyModeOptions): Promise<string>;
@@ -327,6 +339,7 @@ declare function startCaddy(path: string): execa.ResultPromise<{
     cwd: string;
     stdio: "inherit" | "pipe";
 }>;
+declare function stopCaddyProcesses(pids: Iterable<number>, killProcess?: CaddyProcessKiller): CaddyProcessStopResult;
 declare function trustCaddy(path: string): Promise<void>;
 
 type ResolveGhostTunnelRequestInput = {
@@ -402,6 +415,10 @@ type LocalghostContextOptions = {
     bindHost?: string | boolean;
     primaryHost?: string;
     dynamicPort?: boolean;
+    reservePort?: boolean;
+    instanceKey?: string;
+    reservedPorts?: Iterable<number>;
+    registryOwnerToken?: string;
     autoRepair?: boolean;
     command?: string[];
     services?: LocalghostServiceOptions[];
@@ -427,6 +444,7 @@ type LocalghostContext = {
     wwwAlias: boolean;
     ghostTunnel: GhostTunnelConfig;
     projectConfigPath?: string;
+    releasePort?: () => Promise<boolean>;
 };
 type LocalghostProjectConfig = Omit<LocalghostContextOptions, "cwd" | "localghostConfig">;
 type LocalghostProjectConfigResult = {
@@ -504,6 +522,66 @@ type FindAvailablePortOptions = {
 declare function isPortAvailable(port: number, host?: string): Promise<boolean>;
 declare function findAvailablePort(startPort: number, options?: FindAvailablePortOptions): Promise<number>;
 
+declare const LOCALGHOST_REGISTRY_FILE = "registry.json";
+declare const LOCALGHOST_REGISTRY_LOCK_FILE = "registry.lock";
+type PortAvailabilityCheck = (port: number, host?: string) => boolean | Promise<boolean>;
+type LocalghostRegistryEntry = {
+    projectCwd: string;
+    instanceKey: string;
+    port: number;
+    updatedAt: number;
+};
+type LocalghostLease = {
+    projectCwd: string;
+    instanceKey: string;
+    port: number;
+    pid: number;
+    acquiredAt: number;
+    expiresAt: number;
+    ownerToken: string;
+};
+type LocalghostRegistryData = {
+    version: 1;
+    allocations: LocalghostRegistryEntry[];
+    leases: LocalghostLease[];
+};
+type LocalghostRegistryOptions = {
+    stateRoot?: string;
+    cwd?: string;
+    pid?: number;
+    ownerToken?: string;
+    now?: () => number;
+    isProcessRunning?: (pid: number) => boolean;
+    availabilityCheck?: PortAvailabilityCheck;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+    lockStaleMs?: number;
+};
+type AcquireLocalghostPortOptions = {
+    projectCwd?: string;
+    instanceKey: string;
+    startPort?: number;
+    maxAttempts?: number;
+    reservedPorts?: Iterable<number>;
+    leaseTtlMs?: number;
+    host?: string;
+};
+type LocalghostRegistry = {
+    root: string;
+    registryPath: string;
+    lockPath: string;
+    ownerToken: string;
+    acquirePort(options: AcquireLocalghostPortOptions): Promise<LocalghostLease>;
+    releasePort(options: {
+        projectCwd?: string;
+        instanceKey: string;
+    }): Promise<boolean>;
+    read(): Promise<LocalghostRegistryData>;
+};
+declare function getLocalghostRegistryRoot(env?: NodeJS.ProcessEnv): string;
+declare function canonicalizeLocalghostProjectCwd(cwd?: string): string;
+declare function createLocalghostRegistry(options?: LocalghostRegistryOptions): LocalghostRegistry;
+
 type DomainRoute = {
     host: string;
     port: number;
@@ -571,7 +649,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.13";
+declare const LOCALGHOST_VERSION = "0.1.15";
 declare const UPDATE_CHECK_CACHE_TTL_MS: number;
 declare const UPDATE_CHECK_NOTIFY_TTL_MS: number;
 declare const UPDATE_CHECK_TIMEOUT_MS = 900;
@@ -608,4 +686,4 @@ declare function maybeNotifyAboutUpdate(options?: {
     disabled?: boolean;
 }): Promise<void>;
 
-export { type ActiveRelayRoute, type CaddyModeOptions, 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_GHOST_TUNNEL_FILE, LOCALGHOST_PACKAGE_NAME, LOCALGHOST_STATE_FILE, LOCALGHOST_VERSION, type LocalghostActivity, type LocalghostContext, type LocalghostContextOptions, type LocalghostEnvironment, type LocalghostPackageManager, type LocalghostProjectConfig, type LocalghostProjectConfigResult, type LocalghostRunMode, type LocalghostRunRecord, type LocalghostServiceOptions, type LocalghostSetupRecord, type LocalghostState, type LocalghostStateAction, type PackageManager, 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, checkCaddy, checkForUpdate, compareVersions, constructGhostTunnelIpUrl, createGhostTunnelQueuedRequest, createGhostTunnelRouteHeartbeat, createMemoryGhostTunnelStore, createRedisGhostTunnelStore, createRedisGhostTunnelStoreFromEnv, createRelayRouteRegistration, createVercelGhostTunnelHandler, decodeGhostTunnelBody, defineLocalghostConfig, detectDevCommand, detectDevPackageManager, detectDevServices, detectPackageManager, encodeGhostTunnelBody, findAvailablePort, findGhostTunnelEntry, formatDetectedDevCommand, formatDetectedDevServices, formatDomainRoutes, formatGhostTunnel, formatUpdateMessage, getCaddyfilePath, getDomainRoutes, getGhostTunnelPath, getLocalghostActivityPath, 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, 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 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 };