@hamedb89/localghost 0.3.0 → 0.4.1

package/README.md

@@ -45,6 +45,23 @@ Then keep using the command your repo already expects:
 npm exec localghost
 ```
 
+If Localghost is not installed in the repository yet, use an explicit package-manager launcher:
+
+```sh
+npm exec --yes --package=@hamedb89/localghost -- localghost
+pnpm dlx @hamedb89/localghost
+yarn dlx @hamedb89/localghost
+bunx --package @hamedb89/localghost localghost
+```
+
+From a Localghost checkout, test a real consumer repository against the local checkout without changing the consumer's manifest or working tree. This is repository development tooling and is not part of the installed npm package:
+
+```sh
+./bin/ghost consumer test faaast --repo /path/to/faaast-landing -- pnpm run bench:noop
+```
+
+The command creates a detached worktree, installs its dependencies, builds and links the local Localghost checkout, runs the command inside the worktree, and removes the worktree afterward. Add `--keep` before `--` when inspecting the isolated checkout after a failure. The FAAAST adapter uses a separate `.consumer.test` hostname suffix to avoid colliding with a normal `.localhost` development session.
+
 On the first interactive run, Localghost can create `.localghost`, explain the `/etc/hosts` change, write `ops/local/Caddyfile`, and print the browser-facing URL:
 
 ```txt
@@ -87,6 +104,14 @@ Create the repo-local hostname contract:
 localghost init --write-scripts
 ```
 
+Install or update Localghost in the current repository at any time:
+
+```sh
+npm exec --yes --package=@hamedb89/localghost -- localghost upgrade
+```
+
+Once the package is installed locally, use `localghost upgrade` or the package manager's normal update command.
+
 Check whether the machine is ready:
 
 ```sh
@@ -603,9 +628,10 @@ localghost teardown [--project name] [--remove-caddyfile]
 localghost status [--ready] [--json]
 localghost ps [--json]
 localghost update [--json]
-localghost release <patch|minor|major>
-localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust]
-localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--trust] [--dynamic-port] -- command
+localghost upgrade [--cwd path]
+localghost release [patch|minor|major]
+localghost dev [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--clean-caddy] [--trust]
+localghost run [--config file] [--config-pattern regex] [--https|--ssl] [--auto-repair yes|no] [--clean-caddy] [--trust] [--dynamic-port yes|no] -- command
 localghost routes [--https|--ssl]
 localghost print [--config file] [--config-pattern regex]
 ```
@@ -640,7 +666,7 @@ import { localGhostPlugin } from "@hamedb89/localghost/vite";
 - Preview the exact Pages artifact locally with `npm run site:serve`, then open `http://127.0.0.1:4173/`.
 - npm publish is guarded by `prepublishOnly` and the release workflow publishes with npm provenance.
 - To release the CLI, run `localghost release patch`, `localghost release minor`, or `localghost release major`. The command dispatches the **Release** workflow from `main`; it synchronizes version metadata, verifies the package and runtime matrix, commits and tags the bump, publishes npm, and creates a GitHub Release with generated notes. GitHub CLI must be installed and authenticated.
-- From this repository, `./bin/ghost release minor` (or the shorter `./bin/c release minor`) pushes `main` and dispatches the same guarded GitHub release workflow. Use `./bin/ghost check` for the release verification locally, `./bin/ghost release status` to inspect recent runs, or `./bin/ghost release retry v0.2.0` to retry publishing an existing tag.
+- From this repository, `./bin/ghost release minor` (or the shorter `./bin/c release minor`) pushes `main` and dispatches the same guarded GitHub release workflow. Use `./bin/ghost check` for the release verification locally, `./bin/ghost release status` to inspect recent runs, or `./bin/ghost release retry v0.4.0` to retry publishing an existing tag.
 - Runtime dependencies are intentionally small: `commander` and `execa`. Vite is an optional peer dependency.
 - No postinstall scripts, hidden Homebrew installs, surprise browser tabs, or broad hosts-file rewrites.
 - Update checks are best-effort, cached for 24 hours, and can be disabled with `LOCALGHOST_NO_UPDATE_CHECK=1` or `--no-update-check`.

package/dist/cli.js

@@ -1821,30 +1821,44 @@ function shellQuote(value) {
 function getConfigFlag(configFile) {
   return configFile === LOCALGHOST_CONFIG_FILE ? "" : ` --config ${shellQuote(configFile)}`;
 }
-function updatePackageScripts(packageJsonPath, configFile) {
+function hasLocalghostDependency(pkg) {
+  return ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"].some((field) => {
+    const dependencies = pkg[field];
+    return typeof dependencies === "object" && dependencies !== null && "@hamedb89/localghost" in dependencies;
+  });
+}
+function localghostCommand(packageManager, installed) {
+  if (installed) return "localghost";
+  if (packageManager === "pnpm") return "pnpm dlx @hamedb89/localghost";
+  if (packageManager === "yarn") return "yarn dlx @hamedb89/localghost";
+  if (packageManager === "bun") return "bunx --package @hamedb89/localghost localghost";
+  return "npm exec --yes --package=@hamedb89/localghost -- localghost";
+}
+function updatePackageScripts(packageJsonPath, configFile, packageManager) {
   const pkg = readPackageJson2(packageJsonPath);
   if (!pkg) return false;
   const scripts = typeof pkg.scripts === "object" && pkg.scripts ? pkg.scripts : {};
   const configFlag = getConfigFlag(configFile);
+  const command = localghostCommand(packageManager, hasLocalghostDependency(pkg));
   const nextScripts = {
     ...scripts,
-    "localghost:setup": scripts["localghost:setup"] ?? `localghost setup${configFlag}`,
-    "localghost:proxy": scripts["localghost:proxy"] ?? `localghost dev${configFlag}`,
-    "localghost:proxy:https": scripts["localghost:proxy:https"] ?? `localghost dev${configFlag} --https`,
-    "localghost:run": scripts["localghost:run"] ?? `localghost run${configFlag} --`,
-    "localghost:ready": scripts["localghost:ready"] ?? `localghost status${configFlag} --ready`,
-    "localghost:repair": scripts["localghost:repair"] ?? `localghost repair${configFlag}`,
-    "localghost:trust": scripts["localghost:trust"] ?? `localghost trust${configFlag}`,
-    "localghost:ps": scripts["localghost:ps"] ?? "localghost ps",
-    "localghost:print": scripts["localghost:print"] ?? `localghost print${configFlag}`,
-    "localghost:routes": scripts["localghost:routes"] ?? `localghost routes${configFlag}`,
-    "localghost:status": scripts["localghost:status"] ?? "localghost status",
-    "localghost:reset": scripts["localghost:reset"] ?? "localghost reset",
-    "localghost:teardown": scripts["localghost:teardown"] ?? "localghost teardown",
-    "localghost:doctor": scripts["localghost:doctor"] ?? "localghost doctor",
-    "localghost:update": scripts["localghost:update"] ?? "localghost update",
-    "caddy:setup": scripts["caddy:setup"] ?? `localghost setup${configFlag}`,
-    "caddy:dev": scripts["caddy:dev"] ?? `localghost dev${configFlag}`
+    "localghost:setup": scripts["localghost:setup"] ?? `${command} setup${configFlag}`,
+    "localghost:proxy": scripts["localghost:proxy"] ?? `${command} dev${configFlag}`,
+    "localghost:proxy:https": scripts["localghost:proxy:https"] ?? `${command} dev${configFlag} --https`,
+    "localghost:run": scripts["localghost:run"] ?? `${command} run${configFlag} --`,
+    "localghost:ready": scripts["localghost:ready"] ?? `${command} status${configFlag} --ready`,
+    "localghost:repair": scripts["localghost:repair"] ?? `${command} repair${configFlag}`,
+    "localghost:trust": scripts["localghost:trust"] ?? `${command} trust${configFlag}`,
+    "localghost:ps": scripts["localghost:ps"] ?? `${command} ps`,
+    "localghost:print": scripts["localghost:print"] ?? `${command} print${configFlag}`,
+    "localghost:routes": scripts["localghost:routes"] ?? `${command} routes${configFlag}`,
+    "localghost:status": scripts["localghost:status"] ?? `${command} status`,
+    "localghost:reset": scripts["localghost:reset"] ?? `${command} reset`,
+    "localghost:teardown": scripts["localghost:teardown"] ?? `${command} teardown`,
+    "localghost:doctor": scripts["localghost:doctor"] ?? `${command} doctor`,
+    "localghost:update": scripts["localghost:update"] ?? `${command} update`,
+    "caddy:setup": scripts["caddy:setup"] ?? `${command} setup${configFlag}`,
+    "caddy:dev": scripts["caddy:dev"] ?? `${command} dev${configFlag}`
   };
   const changed = JSON.stringify(scripts) !== JSON.stringify(nextScripts);
   if (!changed) return false;
@@ -1880,7 +1894,7 @@ function initLocalghost(options = {}) {
   }
   writeTextFile(configPath, renderConfig({ host, port, apiHost, apiPort }));
   const packageJsonPath = join8(cwd, "package.json");
-  const packageJsonChanged = options.writeScripts ? updatePackageScripts(packageJsonPath, configFile) : false;
+  const packageJsonChanged = options.writeScripts ? updatePackageScripts(packageJsonPath, configFile, packageManager) : false;
   return {
     configPath,
     configCreated: true,
@@ -1903,10 +1917,17 @@ Localghost owns the local development proxy and the app process boundary.
 
 ## Preferred repository setup
 
-For a normal repository, use this package script:
+For a normal repository with Localghost installed as a dev dependency, use this package script:
 
     "dev": "localghost"
 
+If the repository does not have a local CLI yet, use the package-manager launcher:
+
+    npm exec --yes --package=@hamedb89/localghost -- localghost
+    pnpm dlx @hamedb89/localghost
+    yarn dlx @hamedb89/localghost
+    bunx --package @hamedb89/localghost localghost
+
 For an explicit app command, keep the raw command separate:
 
     "dev": "localghost run -- vite"
@@ -1926,6 +1947,11 @@ Use \`localghost dev\` only when the Caddy proxy should run without starting the
 - \`localghost doctor\`: check machine prerequisites, ports, and registry state.
 - \`localghost repair --reallocate-port\`: move an occupied project port to a stable available port.
 
+- \`localghost update\`: check npm for a newer Localghost release.
+- \`localghost upgrade\`: install or update Localghost as a repository dev dependency.
+
+Use \`localghost\` directly when the package is installed locally. Use \`npm exec --yes --package=@hamedb89/localghost -- localghost <command>\`, \`pnpm dlx @hamedb89/localghost <command>\`, \`yarn dlx @hamedb89/localghost <command>\`, or \`bunx --package @hamedb89/localghost localghost <command>\` when it is not.
+
 ## Configuration
 
 - Commit repository defaults in \`localghost.config.mjs\`.
@@ -1942,6 +1968,14 @@ function formatLocalghostAgentGuide(format = "text") {
   if (format === "json") {
     return JSON.stringify({
       preferredScript: "localghost",
+      packageInstall: "npm install -D @hamedb89/localghost",
+      packageUpgrade: "localghost upgrade",
+      packageLaunchers: {
+        npm: "npm exec --yes --package=@hamedb89/localghost -- localghost",
+        pnpm: "pnpm dlx @hamedb89/localghost",
+        yarn: "yarn dlx @hamedb89/localghost",
+        bun: "bunx --package @hamedb89/localghost localghost"
+      },
       explicitScript: "localghost run -- <command>",
       proxyOnlyCommand: "localghost dev",
       inspectionCommands: ["localghost status --ready", "localghost ps --json", "localghost routes", "localghost doctor"],
@@ -2068,7 +2102,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.3.0";
+var LOCALGHOST_VERSION = "0.4.1";
 var UPDATE_CHECK_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
 var UPDATE_CHECK_NOTIFY_TTL_MS = 24 * 60 * 60 * 1e3;
 var UPDATE_CHECK_TIMEOUT_MS = 900;
@@ -2196,7 +2230,8 @@ function formatUpdateMessage(result) {
   if (!result.updateAvailable || !result.latestVersion) return null;
   return [
     `localghost ${result.latestVersion} is available. Current: ${result.currentVersion}`,
-    `Update with: npm i -g ${result.packageName}@latest`
+    "Update a repository with: npm exec --yes --package=@hamedb89/localghost -- localghost upgrade",
+    "If Localghost is already installed locally, run: localghost upgrade"
   ].join("\n");
 }
 function shouldNotifyAboutUpdate(result, cachePath = getUpdateCheckCachePath(), now = Date.now()) {
@@ -2508,6 +2543,21 @@ function registerCleanup(id) {
     process.off("exit", cleanup);
   };
 }
+function registerSignalShutdown(stop) {
+  let requested = false;
+  const request = () => {
+    if (requested) return;
+    requested = true;
+    stop();
+  };
+  process.once("SIGINT", request);
+  process.once("SIGTERM", request);
+  return () => {
+    process.off("SIGINT", request);
+    process.off("SIGTERM", request);
+    request();
+  };
+}
 async function resolveServiceRuntimeEntries(services, dynamicPort, projectCwd) {
   const usedPorts = /* @__PURE__ */ new Set();
   const resolved = [];
@@ -2563,6 +2613,24 @@ async function waitForPortsToBeAvailable(entries, timeoutMs = 1e4) {
   }
   return false;
 }
+async function waitForProcessShutdown(processes, forceStop, timeoutMs = 1e4) {
+  const settled = Promise.allSettled(processes);
+  const completed = await Promise.race([
+    settled.then(() => true),
+    wait2(timeoutMs).then(() => false)
+  ]);
+  if (completed) return true;
+  console.warn("Localghost: timed out waiting for managed processes to stop; escalating termination.");
+  forceStop("SIGTERM");
+  const terminated = await Promise.race([
+    settled.then(() => true),
+    wait2(2e3).then(() => false)
+  ]);
+  if (terminated) return true;
+  forceStop("SIGKILL");
+  await Promise.race([settled, wait2(1e3)]);
+  return false;
+}
 async function runDetectedServices(options) {
   assertLocalDevelopment("run");
   await assertCaddyReady();
@@ -2628,6 +2696,13 @@ async function runDetectedServices(options) {
     });
     const cleanupRun = registerCleanup(runRecord.id);
     const processExit = Promise.race([caddyExit, ...children]);
+    const stopManaged = (signal) => {
+      for (const child of children) {
+        signalManagedProcess(child, signal);
+      }
+      signalManagedProcess(caddy, signal);
+    };
+    const finishShutdown = registerSignalShutdown(() => stopManaged("SIGINT"));
     try {
       const ready = await Promise.race([
         waitForServicePorts(entries),
@@ -2639,13 +2714,17 @@ async function runDetectedServices(options) {
       }
       await processExit;
     } finally {
-      for (const child of children) {
-        signalManagedProcess(child, "SIGINT");
-      }
-      signalManagedProcess(caddy, "SIGINT");
-      await Promise.allSettled([caddyExit, ...children]);
+      finishShutdown();
+      await waitForProcessShutdown(
+        [caddyExit, ...children],
+        stopManaged
+      );
       if (!await waitForPortsToBeAvailable(entries)) {
         console.warn("Localghost: timed out waiting for service ports to be released.");
+        stopManaged("SIGTERM");
+        if (!await waitForPortsToBeAvailable(entries, 2e3)) {
+          stopManaged("SIGKILL");
+        }
       }
       cleanupRun();
     }
@@ -2746,7 +2825,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" || actionCommand.name() === "release") return;
+  if (["update", "upgrade", "release"].includes(actionCommand.name())) return;
   const options = program.opts();
   await maybeNotifyAboutUpdate({ disabled: options.updateCheck === false });
 });
@@ -2825,7 +2904,15 @@ 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) => {
+program.command("upgrade").description("Install or update Localghost in the current repository").option("--cwd <path>", "Consumer repository", process.cwd()).action(async (options) => {
+  const packageManager = detectPackageManager(options.cwd);
+  const packageName = "@hamedb89/localghost@latest";
+  const args = packageManager === "yarn" ? ["add", "--dev", packageName] : packageManager === "pnpm" ? ["add", "--save-dev", packageName] : packageManager === "bun" ? ["add", "--dev", packageName] : ["install", "--save-dev", packageName];
+  console.log(`Upgrading ${packageName} with ${packageManager}...`);
+  await execa4(packageManager, args, { cwd: options.cwd, stdio: "inherit" });
+  console.log(`Localghost is upgraded in ${options.cwd}.`);
+});
+program.command("release").description("Dispatch an automated Localghost CLI release").argument("[bump]", "Semantic version increment: patch, minor, or major (default: patch)", parseReleaseBump, "patch").action(async (bump) => {
   const repository = "hamedb89/localghost";
   try {
     await execa4("gh", [
@@ -3223,20 +3310,25 @@ program.command("run").description("Run Caddy and a dev command from the same Lo
     entries: context.entries
   });
   const cleanupRun = registerCleanup(runRecord.id);
-  const stopCaddy = () => {
-    signalManagedProcess(caddy, "SIGINT");
-  };
-  const stopChild = () => {
-    signalManagedProcess(child, "SIGINT");
+  const stopManaged = (signal) => {
+    signalManagedProcess(child, signal);
+    signalManagedProcess(caddy, signal);
   };
+  const finishShutdown = registerSignalShutdown(() => stopManaged("SIGINT"));
   try {
     await Promise.race([child, caddyExit]);
   } finally {
-    stopChild();
-    stopCaddy();
-    await Promise.allSettled([child, caddyExit]);
+    finishShutdown();
+    await waitForProcessShutdown(
+      [child, caddyExit],
+      stopManaged
+    );
     if (!await waitForPortsToBeAvailable(context.entries)) {
       console.warn("Localghost: timed out waiting for service ports to be released.");
+      stopManaged("SIGTERM");
+      if (!await waitForPortsToBeAvailable(context.entries, 2e3)) {
+        stopManaged("SIGKILL");
+      }
     }
     cleanupRun();
     await context.releasePort?.();
@@ -3415,9 +3507,11 @@ async function main() {
     ...detected.command
   ]);
 }
-main().catch((error) => {
+main().then(() => {
+  process.exit(process.exitCode ?? 0);
+}).catch((error) => {
   const message = error instanceof Error ? error.message : String(error);
   console.error(message);
-  process.exitCode = 1;
+  process.exit(1);
 });
 //# sourceMappingURL=cli.js.map