@hamedb89/localghost 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -72,7 +72,7 @@ declare function unregisterLocalghostSetup(options: {
 declare function renderLocalghostBanner(): string;
 declare function renderCompactLocalghostBanner(): string;
 
-declare const LOCALGHOST_AGENT_GUIDE = "# Localghost agent guide\n\nLocalghost owns the local development proxy and the app process boundary.\n\n## Preferred repository setup\n\nFor a normal repository, use this package script:\n\n    \"dev\": \"localghost\"\n\nFor an explicit app command, keep the raw command separate:\n\n    \"dev\": \"localghost run -- vite\"\n    \"dev:raw\": \"vite\"\n\nUse `localghost dev` only when the Caddy proxy should run without starting the app.\n\n## Useful commands\n\n- `localghost`: detect and run the repository development command.\n- `localghost run -- <command>`: wrap an explicit app command.\n- `localghost dev`: run only the local Caddy proxy.\n- `localghost status --ready`: check project setup.\n- `localghost repair`: repair managed hosts and Caddy setup.\n- `localghost ps --json`: inspect Localghost-managed repositories, instances, and ports.\n- `localghost routes`: inspect hostname-to-port routing.\n- `localghost doctor`: check machine prerequisites, ports, and registry state.\n- `localghost repair --reallocate-port`: move an occupied project port to a stable available port.\n\n## Configuration\n\n- Commit repository defaults in `localghost.config.mjs`.\n- Keep hostname and requested-port routes in `.localghost`.\n- CLI flags override repository configuration for one invocation.\n- Localghost remembers active project and instance port assignments in user state under `~/.localghost`.\n- Do not edit the registry manually and do not start Caddy separately.\n\n## Port behavior\n\nLocalghost remembers ports by canonical repository path and instance key. Concurrent Localghost instances receive distinct ports. The operating-system bind check remains authoritative when another tool already owns a port.\n";
+declare 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 with Localghost installed as a dev dependency, use this package script:\n\n    \"dev\": \"localghost\"\n\nIf the repository does not have a local CLI yet, use the package-manager launcher:\n\n    npm exec --yes --package=@hamedb89/localghost -- localghost\n    pnpm dlx @hamedb89/localghost\n    yarn dlx @hamedb89/localghost\n    bunx --package @hamedb89/localghost localghost\n\nFor an explicit app command, keep the raw command separate:\n\n    \"dev\": \"localghost run -- vite\"\n    \"dev:raw\": \"vite\"\n\nUse `localghost dev` only when the Caddy proxy should run without starting the app.\n\n## Useful commands\n\n- `localghost`: detect and run the repository development command.\n- `localghost run -- <command>`: wrap an explicit app command.\n- `localghost dev`: run only the local Caddy proxy.\n- `localghost status --ready`: check project setup.\n- `localghost repair`: repair managed hosts and Caddy setup.\n- `localghost ps --json`: inspect Localghost-managed repositories, instances, and ports.\n- `localghost routes`: inspect hostname-to-port routing.\n- `localghost doctor`: check machine prerequisites, ports, and registry state.\n- `localghost repair --reallocate-port`: move an occupied project port to a stable available port.\n\n- `localghost update`: check npm for a newer Localghost release.\n- `localghost upgrade`: install or update Localghost as a repository dev dependency.\n\nUse `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.\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";
@@ -685,7 +685,7 @@ type CreateVercelGhostTunnelHandlerOptions = {
 declare function createVercelGhostTunnelHandler(options: CreateVercelGhostTunnelHandlerOptions): (request: VercelGhostTunnelRequestLike, response: VercelGhostTunnelResponseLike) => Promise<void>;
 
 declare const LOCALGHOST_PACKAGE_NAME = "@hamedb89/localghost";
-declare const LOCALGHOST_VERSION = "0.3.0";
+declare const LOCALGHOST_VERSION = "0.4.0";
 declare const UPDATE_CHECK_CACHE_TTL_MS: number;
 declare const UPDATE_CHECK_NOTIFY_TTL_MS: number;
 declare const UPDATE_CHECK_TIMEOUT_MS = 900;

package/dist/index.js

@@ -282,10 +282,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"
@@ -305,6 +312,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\`.
@@ -321,6 +333,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"],
@@ -2452,30 +2472,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;
@@ -2511,7 +2545,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,
@@ -2865,7 +2899,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.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;
@@ -2993,7 +3027,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()) {