@hamedb89/localghost 0.1.15 → 0.2.0

package/README.md

@@ -93,6 +93,8 @@ Check whether the machine is ready:
 localghost doctor
 ```
 
+Doctor also reports occupied configured ports, stale registry leases, and port allocations shared by multiple Localghost instances. Use `--json` for agent-readable output.
+
 Prepare `/etc/hosts` and the local Caddyfile:
 
 ```sh
@@ -111,6 +113,14 @@ Repair stale hosts, Caddy configuration, or setup state:
 localghost repair
 ```
 
+If an existing project port is occupied or was allocated incorrectly, ask Localghost to choose and remember the next available port:
+
+```sh
+localghost repair --reallocate-port
+```
+
+This does not edit `.localghost`; it records a stable runtime allocation in `~/.localghost` and regenerates the managed hosts and Caddy state from that allocation. To remove expired or dead leases as part of the repair, add `--prune-registry`.
+
 Run only the local proxy:
 
 ```sh
@@ -584,9 +594,9 @@ The app bundle is written to `dist/LocalghostWidget.app`.
 ```sh
 localghost [--cwd path] [--dry-run]
 localghost init [--write-scripts] [--config file] [--host host] [--port port]
-localghost doctor
+localghost doctor [--cwd path] [--config file] [--config-pattern regex] [--json]
 localghost setup [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
-localghost repair [--project name] [--config file] [--config-pattern regex] [--https|--ssl] [--trust]
+localghost repair [--project name] [--config file] [--config-pattern regex] [--https|--ssl] [--trust] [--reallocate-port] [--prune-registry]
 localghost trust [--project name] [--config file] [--config-pattern regex] [--https|--ssl]
 localghost reset [--project name]
 localghost teardown [--project name] [--remove-caddyfile]

package/dist/cli.js

@@ -86,6 +86,7 @@ function registerLocalghostRun(input2, path = getLocalghostActivityPath()) {
     ...input2.configPath ? { configPath: input2.configPath } : {},
     ...input2.caddyfilePath ? { caddyfilePath: input2.caddyfilePath } : {},
     ...input2.caddyPid ? { caddyPid: input2.caddyPid } : {},
+    ...input2.caddyPgid ? { caddyPgid: input2.caddyPgid } : {},
     ...input2.childPid ? { childPid: input2.childPid } : {},
     ...input2.childCommand ? { childCommand: input2.childCommand } : {},
     ...typeof input2.https === "boolean" ? { https: input2.https } : {},
@@ -336,7 +337,8 @@ async function validateCaddyfile(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)) {
@@ -628,6 +630,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");
@@ -1207,11 +1221,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
+        }
+      } : {}
+    }
   };
 }
 
@@ -1868,7 +1923,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
 
@@ -2012,7 +2068,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.2.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;
@@ -2176,6 +2232,27 @@ ${message}`);
 
 // src/cli.ts
 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;
+  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/cli.ts
 function warnAboutLocalMdns(entries) {
   const localHosts = findLocalMdnsHosts(entries);
   if (localHosts.length > 0) {
@@ -2255,10 +2332,18 @@ async function assertCaddyReady() {
 }
 function cleanManagedCaddyProcesses() {
   const runs = listLocalghostRuns();
-  const caddyPids = runs.flatMap((run) => run.caddyPid ? [run.caddyPid] : []);
-  const result = stopCaddyProcesses(caddyPids);
+  const legacyPids = runs.flatMap((run) => run.caddyPid && !run.caddyPgid ? [run.caddyPid] : []);
+  const managedPgid = runs.flatMap((run) => run.caddyPgid ? [run.caddyPgid] : []);
+  const legacyResult = stopCaddyProcesses(legacyPids);
+  const managedResult = stopCaddyProcesses(managedPgid, signalManagedProcessPid);
+  const result = {
+    stopped: [...legacyResult.stopped, ...managedResult.stopped],
+    alreadyExited: [...legacyResult.alreadyExited, ...managedResult.alreadyExited],
+    failed: [...legacyResult.failed, ...managedResult.failed]
+  };
   for (const run of runs) {
-    if (run.caddyPid && (result.stopped.includes(run.caddyPid) || result.alreadyExited.includes(run.caddyPid))) {
+    const caddyIdentity = run.caddyPgid ?? run.caddyPid;
+    if (caddyIdentity && (result.stopped.includes(caddyIdentity) || result.alreadyExited.includes(caddyIdentity))) {
       unregisterLocalghostRun(run.id);
     }
   }
@@ -2468,6 +2553,16 @@ async function waitForServicePorts(entries, timeoutMs = 1e4) {
   }
   return false;
 }
+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;
+    await wait2(50);
+  }
+  return false;
+}
 async function runDetectedServices(options) {
   assertLocalDevelopment("run");
   await assertCaddyReady();
@@ -2508,6 +2603,7 @@ async function runDetectedServices(options) {
     const children = runtimeServices.map((service) => execa4(service.command[0], service.command.slice(1), {
       cwd: service.cwd,
       stdio: "inherit",
+      detached: process.platform !== "win32",
       env: {
         ...process.env,
         LOCALGHOST_PORT: String(service.port),
@@ -2524,6 +2620,7 @@ async function runDetectedServices(options) {
       configPath: options.configPath,
       caddyfilePath: caddyfile,
       ...caddyPid ? { caddyPid } : {},
+      ...caddyPid ? { caddyPgid: caddyPid } : {},
       childCommand: ["services", ...runtimeServices.map((service) => service.name)],
       https: options.https,
       dynamicPort: options.dynamicPort,
@@ -2543,10 +2640,13 @@ async function runDetectedServices(options) {
       await processExit;
     } finally {
       for (const child of children) {
-        if (!child.killed) child.kill("SIGINT");
+        signalManagedProcess(child, "SIGINT");
       }
-      if (!caddy.killed) caddy.kill("SIGINT");
+      signalManagedProcess(caddy, "SIGINT");
       await Promise.allSettled([caddyExit, ...children]);
+      if (!await waitForPortsToBeAvailable(entries)) {
+        console.warn("Localghost: timed out waiting for service ports to be released.");
+      }
       cleanupRun();
     }
   } finally {
@@ -2674,8 +2774,17 @@ program.command("init").description("Create a .localghost config for this projec
 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();
+program.command("doctor").description("Check machine prerequisites, ports, and Localghost registry state").option("--cwd <path>", "Project directory", process.cwd()).option("--config <file>", "Config file to inspect. Can be repeated.", collect, []).option("--config-pattern <regex>", "Regex for config filenames in the project root").option("--json", "Print raw JSON").action(async (options) => {
+  const result = await runDoctor({
+    cwd: options.cwd,
+    ...options.config && options.config.length > 0 ? { configFiles: options.config } : {},
+    ...options.configPattern ? { configPattern: options.configPattern } : {}
+  });
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
   if (result.caddy.found) {
     console.log(`Caddy: ${result.caddy.version ?? "found"}`);
   } else {
@@ -2683,6 +2792,17 @@ program.command("doctor").description("Check machine prerequisites").action(asyn
     console.log(`Run: ${result.caddy.installHint}`);
     console.log("Localghost will not install it for you. No surprise spells.");
   }
+  if (result.ports.configured === void 0) {
+    console.log("Port: could not resolve project configuration.");
+  } else {
+    console.log(`Port ${result.ports.configured}: ${result.ports.available ? "available" : "occupied"}`);
+  }
+  if (result.ports.staleLeases.length > 0) {
+    console.log(`Registry: ${result.ports.staleLeases.length} stale lease(s); run localghost repair --prune-registry.`);
+  }
+  for (const duplicate of result.ports.duplicateAllocations) {
+    console.log(`Registry: port ${duplicate.port} is allocated to ${duplicate.projects.join(", ")}.`);
+  }
   if (!result.ok) {
     process.exitCode = 1;
   }
@@ -2789,11 +2909,20 @@ program.command("trust").description("Trust Caddy's local HTTPS CA for this proj
   await validateCaddyfile(caddyfile);
   await runTrust(options.cwd, caddyfile);
 });
-program.command("repair").description("Reconcile stale hosts, Caddyfile, setup state, and optional HTTPS trust").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", "Repair an HTTPS Caddy setup").option("--ssl", "Alias for --https").option("--trust", "Re-run Caddy's local HTTPS trust step").action(async (options) => {
+program.command("repair").description("Reconcile stale setup, ports, registry state, and optional HTTPS trust").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", "Repair an HTTPS Caddy setup").option("--ssl", "Alias for --https").option("--trust", "Re-run Caddy's local HTTPS trust step").option("--reallocate-port", "Persist a stable replacement for an occupied port").option("--prune-registry", "Remove expired or dead registry leases").action(async (options) => {
   assertLocalDevelopment("repair");
   printLocalghostBanner();
   await assertCaddyReady();
-  const context = await resolveLocalghostContext({ ...contextOptionsFromCli(options), dynamicPort: false });
+  const registry = createLocalghostRegistry({ cwd: options.cwd });
+  if (options.pruneRegistry) {
+    const result = await registry.prune();
+    console.log(`Pruned ${result.removedLeases} stale registry lease${result.removedLeases === 1 ? "" : "s"}.`);
+  }
+  const context = await resolveLocalghostContext({
+    ...contextOptionsFromCli(options),
+    dynamicPort: options.reallocatePort ? true : false,
+    ...options.reallocatePort ? { reservePort: true, instanceKey: "run" } : {}
+  });
   const readiness = getSetupReadiness({
     ...options,
     https: context.https,
@@ -2806,14 +2935,21 @@ program.command("repair").description("Reconcile stale hosts, Caddyfile, setup s
   }
   warnAboutLocalMdns(context.entries);
   logDomainRoutes(context.entries, { https: context.https, ghostTunnel: context.ghostTunnel });
-  await runSetupFromReadiness(options.cwd, context.https, readiness);
-  if (options.trust) {
-    await runTrust(options.cwd, readiness.caddyfilePath);
-  }
-  console.log(`Repaired hosts: ${getSystemHostsPath()}`);
-  console.log(`Repaired Caddyfile: ${readiness.caddyfilePath}`);
-  console.log(`Repaired state: ${readiness.statePath}`);
-  console.log("Repair complete.");
+  try {
+    await runSetupFromReadiness(options.cwd, context.https, readiness);
+    if (options.trust) {
+      await runTrust(options.cwd, readiness.caddyfilePath);
+    }
+    if (context.port !== context.requestedPort) {
+      console.log(`Reallocated port ${context.requestedPort} -> ${context.port}.`);
+    }
+    console.log(`Repaired hosts: ${getSystemHostsPath()}`);
+    console.log(`Repaired Caddyfile: ${readiness.caddyfilePath}`);
+    console.log(`Repaired state: ${readiness.statePath}`);
+    console.log("Repair complete.");
+  } finally {
+    await context.releasePort?.();
+  }
 });
 program.command("reset").description("Remove Localghost setup state without deleting .localghost").option("--project <name>", "Managed /etc/hosts block name").option("--cwd <path>", "Project directory", process.cwd()).action(async (options) => {
   assertLocalDevelopment("reset");
@@ -2969,7 +3105,7 @@ program.command("dev").description("Run the Localghost Caddy proxy, repairing st
       ...typeof options.trust === "boolean" ? { trust: options.trust } : {}
     });
   } catch (error) {
-    if (!caddy.killed) caddy.kill("SIGINT");
+    signalManagedProcess(caddy, "SIGINT");
     throw error;
   }
   const caddyPid = maybePid(caddy.pid);
@@ -2980,6 +3116,7 @@ program.command("dev").description("Run the Localghost Caddy proxy, repairing st
     configPath: readiness.configPath,
     caddyfilePath: caddyfile,
     ...caddyPid ? { caddyPid } : {},
+    ...caddyPid ? { caddyPgid: caddyPid } : {},
     https,
     entries: readiness.entries
   });
@@ -3049,7 +3186,7 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
       ...typeof options.trust === "boolean" ? { trust: options.trust } : {}
     });
   } catch (error) {
-    if (!caddy.killed) caddy.kill("SIGINT");
+    signalManagedProcess(caddy, "SIGINT");
     throw error;
   }
   const [binary, ...args] = command;
@@ -3059,6 +3196,7 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
   const child = execa4(binary, args, {
     cwd: options.cwd,
     stdio: "inherit",
+    detached: process.platform !== "win32",
     env: {
       ...process.env,
       LOCALGHOST_PORT: String(context.port),
@@ -3075,6 +3213,7 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
     configPath: context.configPath,
     caddyfilePath: caddyfile,
     ...caddyPid ? { caddyPid } : {},
+    ...caddyPid ? { caddyPgid: caddyPid } : {},
     ...childPid ? { childPid } : {},
     childCommand: command,
     https,
@@ -3085,10 +3224,10 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
   });
   const cleanupRun = registerCleanup(runRecord.id);
   const stopCaddy = () => {
-    if (!caddy.killed) caddy.kill("SIGINT");
+    signalManagedProcess(caddy, "SIGINT");
   };
   const stopChild = () => {
-    if (!child.killed) child.kill("SIGINT");
+    signalManagedProcess(child, "SIGINT");
   };
   try {
     await Promise.race([child, caddyExit]);
@@ -3096,6 +3235,9 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
     stopChild();
     stopCaddy();
     await Promise.allSettled([child, caddyExit]);
+    if (!await waitForPortsToBeAvailable(context.entries)) {
+      console.warn("Localghost: timed out waiting for service ports to be released.");
+    }
     cleanupRun();
     await context.releasePort?.();
   }