@hamedb89/localghost 0.1.12 → 0.1.15

package/README.md

@@ -9,7 +9,7 @@ Buh. Friendly local hostnames for app repos.
 [![CI](https://github.com/hamedb89/localghost/actions/workflows/ci.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/ci.yml)
 [![GitHub Pages](https://github.com/hamedb89/localghost/actions/workflows/pages.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/pages.yml)
 [![Publish npm](https://github.com/hamedb89/localghost/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/hamedb89/localghost/actions/workflows/publish-npm.yml)
-[![npm version](https://img.shields.io/badge/npm-v0.1.12-CB3837?logo=npm)](https://www.npmjs.com/package/@hamedb89/localghost)
+[![npm version](https://img.shields.io/npm/v/@hamedb89/localghost?logo=npm)](https://www.npmjs.com/package/@hamedb89/localghost)
 
 Localghost is a tiny Node.js CLI for clean local app domains. Add it as a dev dependency, keep running the command your team already knows, and use `http://app.localhost/` instead of remembering which port belongs to which process.
 
@@ -20,9 +20,14 @@ Localghost is a tiny Node.js CLI for clean local app domains. Add it as a dev de
 Install it as a dev dependency:
 
 ```sh
+npm install -D @hamedb89/localghost
+pnpm add -D @hamedb89/localghost
 yarn add -D @hamedb89/localghost
+bun add -d @hamedb89/localghost
 ```
 
+Use the command for your package manager; you only need one of the four lines above.
+
 For Vite apps, add the plugin once:
 
 ```ts
@@ -37,7 +42,7 @@ export default defineConfig({
 Then keep using the command your repo already expects:
 
 ```sh
-yarn dev
+npm exec localghost
 ```
 
 On the first interactive run, Localghost can create `.localghost`, explain the `/etc/hosts` change, write `ops/local/Caddyfile`, and print the browser-facing URL:
@@ -54,7 +59,7 @@ For non-Vite apps, wrap your raw dev command:
 ```json
 {
   "scripts": {
-    "dev": "localghost run -- yarn dev:raw",
+    "dev": "localghost run -- next dev",
     "dev:raw": "next dev"
   }
 }
@@ -74,6 +79,8 @@ Localghost detects the package manager, prefers a non-recursive `dev:raw` script
 npm exec localghost -- --dry-run
 ```
 
+Supported runtime flags such as `--https`, `--clean-caddy`, `--auto-repair`, and `--dynamic-port` are forwarded by the bare command to the underlying run lifecycle.
+
 Create the repo-local hostname contract:
 
 ```sh
@@ -135,6 +142,15 @@ localghost ps
 localghost ps --json
 ```
 
+Give coding agents the supported workflow and repository conventions:
+
+```sh
+localghost guide --agent
+localghost guide --agent --json
+```
+
+Localghost remembers project and instance port assignments in user-level state under `~/.localghost`. The registry is used only for Localghost-managed processes; the operating-system port check remains authoritative for unrelated processes.
+
 Check for updates:
 
 ```sh
@@ -218,14 +234,14 @@ admin.app.localhost 5174
 }
 ```
 
-### Keep `yarn dev` As The Daily Command
+### Keep Your Existing Dev Command
 
 Wrap the raw app server so teammates keep typing the normal command:
 
 ```json
 {
   "scripts": {
-    "dev": "localghost run -- yarn dev:raw",
+    "dev": "localghost run -- vite",
     "dev:raw": "vite"
   }
 }
@@ -236,7 +252,7 @@ For Turborepo, wrap the dev runner and keep dev uncached:
 ```json
 {
   "scripts": {
-    "dev": "localghost run -- yarn dev:raw",
+    "dev": "localghost run -- turbo dev",
     "dev:raw": "turbo dev"
   }
 }
@@ -307,7 +323,6 @@ export default defineLocalghostConfig({
   port: 5173,
   dynamicPort: true,
   autoRepair: true,
-  command: ["pnpm", "dev"],
   wwwAlias: true
 });
 ```
@@ -329,15 +344,13 @@ export default defineLocalghostConfig({
       name: "web",
       cwd: "apps/web",
       host: "xyz.localhost",
-      port: 5173,
-      command: ["pnpm", "dev"]
+      port: 5173
     },
     {
       name: "api",
       cwd: "apps/api",
       host: "api.xyz.localhost",
-      port: 8787,
-      command: ["pnpm", "dev"]
+      port: 8787
     }
   ]
 });
@@ -415,7 +428,10 @@ export default defineLocalghostConfig({
 });
 ```
 
-### Public Ghost Tunnel
+### Public Ghost Tunnel (Experimental)
+
+> [!WARNING]
+> Ghost Tunnel is experimental. Its configuration, transport protocol, and public APIs may change between releases. Do not rely on it for production-critical access, and review its authentication and network exposure before sharing a tunnel.
 
 `ghostTunnel` is an opt-in production URL shape for deployed wildcard endpoints. It does not change local Caddy or `/etc/hosts` setup.
 
@@ -577,6 +593,7 @@ 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 routes [--https|--ssl]
@@ -612,6 +629,7 @@ import { localGhostPlugin } from "@hamedb89/localghost/vite";
 - GitHub Pages is deployed by Actions from the checked-in `site/`, `docs/`, and `assets/` sources.
 - 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.
 - 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`.
@@ -622,7 +640,7 @@ import { localGhostPlugin } from "@hamedb89/localghost/vite";
 - [Rendered docs](https://hamedb89.github.io/localghost/docs/)
 - [User flows](./docs/flows.md)
 - [CLI reference](./docs/localghost.1.md)
-- [Ghost Tunnel guide](./docs/ghost-tunnel.md)
+- [Ghost Tunnel guide (experimental)](./docs/ghost-tunnel.md)
 - [macOS widget notes](./docs/macos-widget.md)
 - [Brand guidelines](./docs/brand.md)