@hamedb89/localghost 0.1.13 → 0.1.15

package/dist/cli.js

@@ -250,7 +250,12 @@ 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";
 }
 
@@ -334,6 +339,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),
@@ -454,19 +479,19 @@ function formatDetectedDevServices(services) {
 
 // src/context.ts
 import { existsSync as existsSync4, readFileSync as readFileSync5 } from "fs";
-import { join as join5 } from "path";
+import { join as join6 } 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);
   });
@@ -483,6 +508,176 @@ async function findAvailablePort(startPort, options = {}) {
   throw new Error(`No available port found from ${startPort} to ${startPort + maxAttempts - 1}.`);
 }
 
+// src/registry.ts
+import { randomUUID } from "crypto";
+import { mkdir, open, readFile, rename, rm, stat, unlink, writeFile } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { join as join5, normalize, resolve as resolve3 } 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 resolve3(env.LOCALGHOST_HOME || join5(homedir2(), ".localghost"));
+}
+function canonicalizeLocalghostProjectCwd(cwd = process.cwd()) {
+  return normalize(resolve3(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 = resolve3(options.stateRoot ?? getLocalghostRegistryRoot());
+  const registryPath = join5(root, LOCALGHOST_REGISTRY_FILE);
+  const lockPath = join5(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 ?? randomUUID();
+  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 = join5(root, `.registry.${process.pid}.${randomUUID()}.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 = randomUUID();
+    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/tunnel.ts
 import { domainToASCII } from "url";
 var DEFAULT_GHOST_TUNNEL_SUBDOMAIN = "ghost";
@@ -860,7 +1055,7 @@ function envHttps() {
 }
 function getPackageName(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync5(join5(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync5(join6(cwd, "package.json"), "utf8"));
     return typeof pkg.name === "string" ? pkg.name : void 0;
   } catch {
     return void 0;
@@ -943,7 +1138,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);
@@ -972,7 +1184,8 @@ async function resolveLocalghostContext(options = {}) {
     https: merged.https ?? envHttps() ?? false,
     wwwAlias,
     ghostTunnel,
-    ...projectConfig.path ? { projectConfigPath: projectConfig.path } : {}
+    ...projectConfig.path ? { projectConfigPath: projectConfig.path } : {},
+    ...releasePort ? { releasePort } : {}
   };
 }
 
@@ -1041,7 +1254,7 @@ function listGhostTunnelEntries(options = {}) {
 }
 
 // src/ghost-agent.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID as randomUUID3 } from "crypto";
 
 // src/relay.ts
 import { createHmac, timingSafeEqual } from "crypto";
@@ -1153,7 +1366,7 @@ function stripRelayForwardHeaders(headers) {
 }
 
 // src/ghost-tunnel-store.ts
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 function base64Encode(value) {
   return value.toString("base64");
 }
@@ -1191,13 +1404,18 @@ 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 RedisGhostTunnelStore = class {
   url;
   token;
   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;
@@ -1285,11 +1503,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 });
@@ -1375,7 +1593,7 @@ function startGhostTunnelAgent(options) {
   const controller = new AbortController();
   const localSignal = controller.signal;
   const signal = options.signal;
-  const agentId = options.agentId ?? `localghost-${randomUUID2()}`;
+  const agentId = options.agentId ?? `localghost-${randomUUID3()}`;
   const targetHost = options.targetHost ?? "127.0.0.1";
   const routeTtlSeconds = options.routeTtlSeconds ?? 30;
   const requestTtlSeconds = options.requestTtlSeconds ?? 60;
@@ -1430,7 +1648,7 @@ function startGhostTunnelAgent(options) {
 // 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, "\\$&");
@@ -1473,7 +1691,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");
@@ -1511,11 +1729,11 @@ 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(join7(cwd, "bun.lock")) || existsSync5(join7(cwd, "bun.lockb"))) return "bun";
+  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) {
@@ -1589,7 +1807,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 {
@@ -1606,7 +1824,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,
@@ -1623,6 +1841,62 @@ function initLocalghost(options = {}) {
   };
 }
 
+// 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/prompt.ts
 import { stdin as input, stdout as output } from "process";
 import { createInterface } from "readline/promises";
@@ -1711,10 +1985,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);
@@ -1735,10 +2009,10 @@ 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 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.13";
+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;
@@ -1750,8 +2024,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;
@@ -1803,7 +2077,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: {
@@ -1938,6 +2212,10 @@ 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.");
 }
+function parseReleaseBump(value) {
+  if (value === "patch" || value === "minor" || value === "major") return value;
+  throw new InvalidArgumentError("Release bump must be patch, minor, or major.");
+}
 function collect(value, previous = []) {
   return [...previous, value];
 }
@@ -1975,6 +2253,25 @@ async function assertCaddyReady() {
     "Localghost will not install it for you. No surprise spells."
   ].join("\n"));
 }
+function cleanManagedCaddyProcesses() {
+  const runs = listLocalghostRuns();
+  const caddyPids = runs.flatMap((run) => run.caddyPid ? [run.caddyPid] : []);
+  const result = stopCaddyProcesses(caddyPids);
+  for (const run of runs) {
+    if (run.caddyPid && (result.stopped.includes(run.caddyPid) || result.alreadyExited.includes(run.caddyPid))) {
+      unregisterLocalghostRun(run.id);
+    }
+  }
+  if (result.stopped.length > 0) {
+    console.log(`Stopped ${result.stopped.length} Localghost-managed Caddy process${result.stopped.length === 1 ? "" : "es"}.`);
+  }
+  if (result.alreadyExited.length > 0) {
+    console.log(`Removed ${result.alreadyExited.length} stale Localghost Caddy record${result.alreadyExited.length === 1 ? "" : "s"}.`);
+  }
+  if (result.failed.length > 0) {
+    throw new Error(`Could not stop Localghost-managed Caddy PID(s): ${result.failed.map(({ pid }) => pid).join(", ")}.`);
+  }
+}
 function existingTrustMarkers(cwd) {
   const state = readLocalghostState(cwd);
   return {
@@ -2079,7 +2376,7 @@ async function runSetupFromReadiness(cwd, https, readiness) {
   });
 }
 function wait2(ms) {
-  return new Promise((resolve3) => setTimeout(resolve3, ms));
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
 }
 async function runTrust(cwd, caddyfilePath) {
   await wait2(350);
@@ -2126,25 +2423,19 @@ function registerCleanup(id) {
     process.off("exit", cleanup);
   };
 }
-async function resolveServiceRuntimeEntries(services, dynamicPort) {
+async function resolveServiceRuntimeEntries(services, dynamicPort, projectCwd) {
   const usedPorts = /* @__PURE__ */ new Set();
   const resolved = [];
+  const registry = dynamicPort ? createLocalghostRegistry({ cwd: projectCwd, ownerToken: `${process.pid}:services:${projectCwd}` }) : void 0;
   for (const service of services) {
     let port = service.requestedPort;
     if (dynamicPort) {
-      let found = false;
-      for (let offset = 0; offset < 50; offset += 1) {
-        const candidate = service.requestedPort + offset;
-        if (candidate > 65535 || usedPorts.has(candidate)) continue;
-        if (await isPortAvailable(candidate)) {
-          port = candidate;
-          found = true;
-          break;
-        }
-      }
-      if (!found) {
-        throw new Error(`No available port found for service ${service.name} from ${service.requestedPort}.`);
-      }
+      const lease = await registry.acquirePort({
+        instanceKey: `service:${service.name}`,
+        startPort: service.requestedPort,
+        reservedPorts: usedPorts
+      });
+      port = lease.port;
     } else if (usedPorts.has(port)) {
       throw new Error(`Services cannot start separate commands on the same fixed port: ${port}.`);
     }
@@ -2159,7 +2450,13 @@ async function resolveServiceRuntimeEntries(services, dynamicPort) {
       }
     });
   }
-  return resolved;
+  return {
+    services: resolved,
+    release: async () => {
+      if (!registry) return;
+      await Promise.all(resolved.map((service) => registry.releasePort({ instanceKey: `service:${service.name}` })));
+    }
+  };
 }
 async function waitForServicePorts(entries, timeoutMs = 1e4) {
   const deadline = Date.now() + timeoutMs;
@@ -2174,81 +2471,86 @@ async function waitForServicePorts(entries, timeoutMs = 1e4) {
 async function runDetectedServices(options) {
   assertLocalDevelopment("run");
   await assertCaddyReady();
-  const runtimeServices = await resolveServiceRuntimeEntries(options.services, options.dynamicPort);
-  const entries = runtimeServices.map((service) => service.entry);
-  const readiness = getSetupReadiness({
-    cwd: options.cwd,
-    https: options.https,
-    ignoreCaddyfile: true,
-    entries,
-    configPath: options.configPath,
-    projectName: options.projectName
-  });
-  if (!readiness.ready) {
-    if (!options.autoRepair) {
-      throw new Error([
-        "Localghost setup is missing or stale.",
-        ...readiness.reasons.map((reason) => `- ${reason}`),
-        "Automatic repair is disabled. Enable autoRepair or run localghost repair."
-      ].join("\n"));
-    }
-    console.log("Localghost setup is stale; repairing it now.");
-    await runSetupFromReadiness(options.cwd, options.https, readiness);
-  }
-  for (const service of runtimeServices) {
-    if (service.port !== service.requestedPort) {
-      console.log(`${service.name}: port ${service.requestedPort} is busy; using ${service.port}.`);
+  const runtime = await resolveServiceRuntimeEntries(options.services, options.dynamicPort, options.cwd);
+  try {
+    const runtimeServices = runtime.services;
+    const entries = runtimeServices.map((service) => service.entry);
+    const readiness = getSetupReadiness({
+      cwd: options.cwd,
+      https: options.https,
+      ignoreCaddyfile: true,
+      entries,
+      configPath: options.configPath,
+      projectName: options.projectName
+    });
+    if (!readiness.ready) {
+      if (!options.autoRepair) {
+        throw new Error([
+          "Localghost setup is missing or stale.",
+          ...readiness.reasons.map((reason) => `- ${reason}`),
+          "Automatic repair is disabled. Enable autoRepair or run localghost repair."
+        ].join("\n"));
+      }
+      console.log("Localghost setup is stale; repairing it now.");
+      await runSetupFromReadiness(options.cwd, options.https, readiness);
     }
-  }
-  const caddyfile = await writeCaddyfile(entries, options.cwd, { https: options.https });
-  await validateCaddyfile(caddyfile);
-  const caddy = startCaddy(caddyfile);
-  const caddyExit = caddy.catch((error) => {
-    if (!caddy.killed) throw error;
-  });
-  const children = runtimeServices.map((service) => execa4(service.command[0], service.command.slice(1), {
-    cwd: service.cwd,
-    stdio: "inherit",
-    env: {
-      ...process.env,
-      LOCALGHOST_PORT: String(service.port),
-      LOCALGHOST_DYNAMIC_PORT: options.dynamicPort ? "1" : "0",
-      LOCALGHOST_SERVICE: service.name,
-      VITE_PORT: String(service.port)
+    for (const service of runtimeServices) {
+      if (service.port !== service.requestedPort) {
+        console.log(`${service.name}: port ${service.requestedPort} is busy; using ${service.port}.`);
+      }
     }
-  }));
-  const caddyPid = maybePid(caddy.pid);
-  const runRecord = registerLocalghostRun({
-    mode: "run",
-    cwd: options.cwd,
-    projectName: options.projectName,
-    configPath: options.configPath,
-    caddyfilePath: caddyfile,
-    ...caddyPid ? { caddyPid } : {},
-    childCommand: ["services", ...runtimeServices.map((service) => service.name)],
-    https: options.https,
-    dynamicPort: options.dynamicPort,
-    entries
-  });
-  const cleanupRun = registerCleanup(runRecord.id);
-  const processExit = Promise.race([caddyExit, ...children]);
-  try {
-    const ready = await Promise.race([
-      waitForServicePorts(entries),
-      processExit.then(() => false)
-    ]);
-    if (ready) {
-      console.log("");
-      logDomainRoutes(entries, { https: options.https });
+    const caddyfile = await writeCaddyfile(entries, options.cwd, { https: options.https });
+    await validateCaddyfile(caddyfile);
+    const caddy = startCaddy(caddyfile);
+    const caddyExit = caddy.catch((error) => {
+      if (!caddy.killed) throw error;
+    });
+    const children = runtimeServices.map((service) => execa4(service.command[0], service.command.slice(1), {
+      cwd: service.cwd,
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        LOCALGHOST_PORT: String(service.port),
+        LOCALGHOST_DYNAMIC_PORT: options.dynamicPort ? "1" : "0",
+        LOCALGHOST_SERVICE: service.name,
+        VITE_PORT: String(service.port)
+      }
+    }));
+    const caddyPid = maybePid(caddy.pid);
+    const runRecord = registerLocalghostRun({
+      mode: "run",
+      cwd: options.cwd,
+      projectName: options.projectName,
+      configPath: options.configPath,
+      caddyfilePath: caddyfile,
+      ...caddyPid ? { caddyPid } : {},
+      childCommand: ["services", ...runtimeServices.map((service) => service.name)],
+      https: options.https,
+      dynamicPort: options.dynamicPort,
+      entries
+    });
+    const cleanupRun = registerCleanup(runRecord.id);
+    const processExit = Promise.race([caddyExit, ...children]);
+    try {
+      const ready = await Promise.race([
+        waitForServicePorts(entries),
+        processExit.then(() => false)
+      ]);
+      if (ready) {
+        console.log("");
+        logDomainRoutes(entries, { https: options.https });
+      }
+      await processExit;
+    } finally {
+      for (const child of children) {
+        if (!child.killed) child.kill("SIGINT");
+      }
+      if (!caddy.killed) caddy.kill("SIGINT");
+      await Promise.allSettled([caddyExit, ...children]);
+      cleanupRun();
     }
-    await processExit;
   } finally {
-    for (const child of children) {
-      if (!child.killed) child.kill("SIGINT");
-    }
-    if (!caddy.killed) caddy.kill("SIGINT");
-    await Promise.allSettled([caddyExit, ...children]);
-    cleanupRun();
+    await runtime.release();
   }
 }
 async function getRouteViews(entries) {
@@ -2344,7 +2646,7 @@ function formatInstanceViews(instances) {
 var program = new Command();
 program.name("localghost").description("Buh. Friendly local hostnames for app repos.").version(LOCALGHOST_VERSION).option("--no-update-check", "Skip the npm update check for this run");
 program.hook("postAction", async (_thisCommand, actionCommand) => {
-  if (actionCommand.name() === "update") return;
+  if (actionCommand.name() === "update" || actionCommand.name() === "release") return;
   const options = program.opts();
   await maybeNotifyAboutUpdate({ disabled: options.updateCheck === false });
 });
@@ -2369,6 +2671,9 @@ program.command("init").description("Create a .localghost config for this projec
     console.log(`  ${step}`);
   }
 });
+program.command("guide").description("Explain the recommended Localghost workflow to humans or agents").option("--agent", "Print the agent-oriented workflow guide").option("--json", "Print the guide as JSON").action((options) => {
+  console.log(formatLocalghostAgentGuide(options.json ? "json" : "text"));
+});
 program.command("doctor").description("Check machine prerequisites").action(async () => {
   const result = await runDoctor();
   if (result.caddy.found) {
@@ -2400,6 +2705,30 @@ program.command("update").description("Check npm for a newer localghost release"
   }
   console.log(`localghost is up to date. Current: ${result.currentVersion}`);
 });
+program.command("release").description("Dispatch an automated Localghost CLI release").argument("<bump>", "Semantic version increment: patch, minor, or major", parseReleaseBump).action(async (bump) => {
+  const repository = "hamedb89/localghost";
+  try {
+    await execa4("gh", [
+      "workflow",
+      "run",
+      "release.yml",
+      "--repo",
+      repository,
+      "--ref",
+      "main",
+      "-f",
+      `bump=${bump}`
+    ]);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Could not dispatch the Localghost release workflow. Install and authenticate GitHub CLI with \`gh auth login\`, then retry.
+${detail}`
+    );
+  }
+  console.log(`Dispatched a ${bump} Localghost release from main.`);
+  console.log(`Track it at https://github.com/${repository}/actions/workflows/release.yml`);
+});
 program.command("setup").description("Update /etc/hosts and generate/validate Caddyfile").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("--https", "Generate a local HTTPS Caddy proxy with Caddy local certificates").option("--ssl", "Alias for --https").action(async (options) => {
   assertLocalDevelopment("setup");
   printLocalghostBanner();
@@ -2600,9 +2929,10 @@ program.command("routes").description("Print domain to upstream routes").option(
     }));
   }
 });
-program.command("dev").description("Run the Localghost Caddy proxy, repairing stale setup when needed").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("--https", "Run a local HTTPS proxy with Caddy local certificates").option("--ssl", "Alias for --https").option("--setup", "Alias for automatic repair when setup is missing or stale").option("--auto-repair [yes|no]", "Repair stale setup before starting (default: yes)", parseBooleanLike).option("--trust", "Trust Caddy's local HTTPS CA before starting the proxy").action(async (options) => {
+program.command("dev").description("Run the Localghost Caddy proxy, repairing stale setup when needed").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("--https", "Run a local HTTPS proxy with Caddy local certificates").option("--ssl", "Alias for --https").option("--setup", "Alias for automatic repair when setup is missing or stale").option("--auto-repair [yes|no]", "Repair stale setup before starting (default: yes)", parseBooleanLike).option("--clean-caddy", "Stop Localghost-managed Caddy processes before starting").option("--trust", "Trust Caddy's local HTTPS CA before starting the proxy").action(async (options) => {
   assertLocalDevelopment("dev");
   await assertCaddyReady();
+  if (options.cleanCaddy) cleanManagedCaddyProcesses();
   const context = await resolveLocalghostContext({ ...contextOptionsFromCli(options), dynamicPort: false });
   const https = context.https;
   const readiness = getSetupReadiness({
@@ -2660,15 +2990,18 @@ program.command("dev").description("Run the Localghost Caddy proxy, repairing st
     cleanupRun();
   }
 });
-program.command("run").description("Run Caddy and a dev command from the same Localghost context").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("--port <number>", "Initial app port", parsePort2).option("--https", "Run a local HTTPS proxy with Caddy local certificates").option("--ssl", "Alias for --https").option("--setup", "Alias for automatic repair when setup is missing or stale").option("--auto-repair [yes|no]", "Repair stale setup before starting (default: yes)", parseBooleanLike).option("--trust", "Trust Caddy's local HTTPS CA before starting the child command").option("--dynamic-port [yes|no]", "Use the requested port if free, otherwise continue upward", parseBooleanLike).argument("<command...>", "Command to run after --, for example: localghost run -- vite").action(async (command, options) => {
+program.command("run").description("Run Caddy and a dev command from the same Localghost context").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("--port <number>", "Initial app port", parsePort2).option("--https", "Run a local HTTPS proxy with Caddy local certificates").option("--ssl", "Alias for --https").option("--setup", "Alias for automatic repair when setup is missing or stale").option("--auto-repair [yes|no]", "Repair stale setup before starting (default: yes)", parseBooleanLike).option("--clean-caddy", "Stop Localghost-managed Caddy processes before starting").option("--trust", "Trust Caddy's local HTTPS CA before starting the child command").option("--dynamic-port [yes|no]", "Use the requested port if free, otherwise continue upward", parseBooleanLike).argument("<command...>", "Command to run after --, for example: localghost run -- vite").action(async (command, options) => {
   assertLocalDevelopment("run");
   await assertCaddyReady();
+  if (options.cleanCaddy) cleanManagedCaddyProcesses();
   const context = await resolveLocalghostContext({
     cwd: options.cwd,
     ...options.project ? { project: options.project } : {},
     ...options.config && options.config.length > 0 ? { configFiles: options.config } : {},
     ...options.configPattern ? { configPattern: options.configPattern } : {},
     ...options.port ? { port: options.port } : {},
+    reservePort: true,
+    instanceKey: "run",
     ...useHttps(options) ? { https: true } : {},
     ...typeof options.dynamicPort === "boolean" ? { dynamicPort: options.dynamicPort } : {},
     ...typeof options.autoRepair === "boolean" ? { autoRepair: options.autoRepair } : {}
@@ -2764,9 +3097,10 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
     stopCaddy();
     await Promise.allSettled([child, caddyExit]);
     cleanupRun();
+    await context.releasePort?.();
   }
 });
-program.command("tunnel").description("Run the local Ghost Tunnel agent").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("--ghost-config <file>", "Exact Ghost Tunnel route file", ".ghosttunnel").option("--target-host <host>", "Local target host for .ghosttunnel ports", "127.0.0.1").action(async (options) => {
+program.command("tunnel").description("Run the experimental local Ghost Tunnel agent").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("--ghost-config <file>", "Exact Ghost Tunnel route file", ".ghosttunnel").option("--target-host <host>", "Local target host for .ghosttunnel ports", "127.0.0.1").action(async (options) => {
   assertLocalDevelopment("tunnel");
   const context = await resolveLocalghostContext({
     cwd: options.cwd,
@@ -2833,6 +3167,7 @@ function readImplicitInvocation(args) {
   let cwd = process.cwd();
   let dryRun = false;
   let updateCheck = true;
+  const forwardedArgs = [];
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (!arg) continue;
@@ -2844,6 +3179,30 @@ function readImplicitInvocation(args) {
       updateCheck = false;
       continue;
     }
+    if (["--clean-caddy", "--https", "--ssl", "--setup", "--trust"].includes(arg)) {
+      forwardedArgs.push(arg);
+      continue;
+    }
+    if (arg === "--auto-repair" || arg === "--dynamic-port") {
+      const value = args[index + 1];
+      forwardedArgs.push(arg);
+      if (value && !value.startsWith("--")) {
+        forwardedArgs.push(value);
+        index += 1;
+      }
+      continue;
+    }
+    if (arg === "--port" || arg === "--project" || arg === "--config" || arg === "--config-pattern") {
+      const value = args[index + 1];
+      if (!value) throw new Error(`${arg} requires a value.`);
+      forwardedArgs.push(arg, value);
+      index += 1;
+      continue;
+    }
+    if (["--auto-repair=", "--dynamic-port=", "--port=", "--project=", "--config=", "--config-pattern="].some((prefix) => arg.startsWith(prefix))) {
+      forwardedArgs.push(arg);
+      continue;
+    }
     if (arg === "--cwd") {
       const value = args[index + 1];
       if (!value) throw new Error("--cwd requires a path.");
@@ -2857,7 +3216,15 @@ function readImplicitInvocation(args) {
     }
     return null;
   }
-  return { cwd, dryRun, updateCheck };
+  return { cwd, dryRun, updateCheck, forwardedArgs };
+}
+function hasForwardedFlag(args, ...flags) {
+  return args.some((arg) => flags.includes(arg));
+}
+function forwardedBoolean(args, name) {
+  const inline = args.find((arg) => arg.startsWith(`${name}=`));
+  if (inline) return parseBooleanLike(inline.slice(name.length + 1));
+  return args.includes(name) ? true : void 0;
 }
 async function main() {
   const implicit = readImplicitInvocation(process.argv.slice(2));
@@ -2875,14 +3242,15 @@ async function main() {
     });
     console.log(formatDetectedDevServices(services));
     if (implicit.dryRun) return;
+    if (hasForwardedFlag(implicit.forwardedArgs, "--clean-caddy")) cleanManagedCaddyProcesses();
     await runDetectedServices({
       cwd: implicit.cwd,
       services,
       configPath: projectConfig.path,
       projectName: sanitizeProjectName(projectConfig.config.project ?? getProjectName(implicit.cwd)),
-      https: projectConfig.config.https ?? false,
-      dynamicPort: projectConfig.config.dynamicPort ?? true,
-      autoRepair: projectConfig.config.autoRepair ?? true
+      https: hasForwardedFlag(implicit.forwardedArgs, "--https", "--ssl") || (projectConfig.config.https ?? false),
+      dynamicPort: forwardedBoolean(implicit.forwardedArgs, "--dynamic-port") ?? projectConfig.config.dynamicPort ?? true,
+      autoRepair: forwardedBoolean(implicit.forwardedArgs, "--auto-repair") ?? projectConfig.config.autoRepair ?? true
     });
     await maybeNotifyAboutUpdate({ disabled: !implicit.updateCheck });
     return;
@@ -2898,6 +3266,7 @@ async function main() {
     process.argv[1] ?? "localghost",
     ...implicit.updateCheck ? [] : ["--no-update-check"],
     "run",
+    ...implicit.forwardedArgs,
     "--cwd",
     implicit.cwd,
     "--",