@hamedb89/localghost 0.1.12 → 0.1.15

package/docs/flows.md

@@ -5,13 +5,16 @@
 As a developer, I want Localghost to be a drop-in dev dependency so I can add friendly local hostnames without rebuilding the same Caddy and hosts setup in every repo.
 
 ```sh
+npm install -D @hamedb89/localghost
+pnpm add -D @hamedb89/localghost
 yarn add -D @hamedb89/localghost
+bun add -d @hamedb89/localghost
 ```
 
-Then initialize the project contract:
+Choose the install command for the repository's package manager. Then initialize the project contract:
 
 ```sh
-yarn localghost init --write-scripts
+localghost init --write-scripts
 ```
 
 ## Project Contract
@@ -32,7 +35,7 @@ api.app.localhost 8787
 As a developer, I want to know whether my laptop is ready before Localghost changes system files.
 
 ```sh
-yarn localghost doctor
+localghost doctor
 ```
 
 Localghost checks for Caddy and prints the exact install command when it is missing. It does not run Homebrew automatically.
@@ -42,8 +45,8 @@ Localghost checks for Caddy and prints the exact install command when it is miss
 As a developer, I want to know when Localghost itself is stale without paying for a network check on every run.
 
 ```sh
-yarn localghost update
-LOCALGHOST_NO_UPDATE_CHECK=1 yarn localghost doctor
+localghost update
+LOCALGHOST_NO_UPDATE_CHECK=1 localghost doctor
 ```
 
 Localghost checks npm after successful commands, caches the result for 24 hours, and ignores check failures. `LOCALGHOST_NO_UPDATE_CHECK=1` and `--no-update-check` disable the automatic check.
@@ -53,7 +56,7 @@ Localghost checks npm after successful commands, caches the result for 24 hours,
 As a developer, I want one explicit setup command that updates only the managed Localghost block in `/etc/hosts` and validates Caddy.
 
 ```sh
-yarn localghost:setup
+localghost setup
 ```
 
 ## Daily Dev
@@ -61,8 +64,8 @@ yarn localghost:setup
 As a developer, I want a daily command that starts the local HTTP proxy from the same config file, with local HTTPS available only when I ask for it.
 
 ```sh
-yarn localghost:ready
-yarn localghost:proxy
+localghost status --ready
+localghost dev
 ```
 
 Most repos will run this next to their app server, for example Vite on `127.0.0.1:5173`.
@@ -70,7 +73,7 @@ Most repos will run this next to their app server, for example Vite on `127.0.0.
 When a repo really needs local certificates:
 
 ```sh
-yarn localghost:proxy:https
+localghost dev --https
 ```
 
 ## Config Discovery
@@ -78,9 +81,9 @@ yarn localghost:proxy:https
 As a developer, I want Localghost to fit repos that already have naming conventions without hidden file searches.
 
 ```sh
-yarn localghost print --config .localghost.preview
-yarn localghost print --config .localghost.private --config .localghost
-yarn localghost print --config-pattern '^\.localghost\.(private|preview)$'
+localghost print --config .localghost.preview
+localghost print --config .localghost.private --config .localghost
+localghost print --config-pattern '^\.localghost\.(private|preview)$'
 ```
 
 Localghost uses the first existing configured file. Regex discovery scans filenames in the project root.
@@ -90,7 +93,7 @@ Localghost uses the first existing configured file. Regex discovery scans filena
 As a developer, I want to see the local domain layer as a simple `domain -> upstream` map.
 
 ```sh
-yarn localghost routes
+localghost routes
 ```
 
 ```txt
@@ -115,9 +118,11 @@ export default {
 
 The plugin defaults to HTTP. Pass `https: true` only when Vite is expected to sit behind a Caddy HTTPS proxy. Localghost prints URLs but does not open browser tabs.
 
-If `.localghost` is missing, an interactive `yarn dev` asks whether to create it, asks for the primary `.localhost` domain, allows extra domains, explains the `/etc/hosts` password prompt, and runs setup when confirmed. Non-interactive runs fail with the exact setup command instead of guessing.
+If `.localghost` is missing, an interactive development run asks whether to create it, asks for the primary `.localhost` domain, allows extra domains, explains the `/etc/hosts` password prompt, and runs setup when confirmed. Non-interactive runs fail with the exact setup command instead of guessing.
+
+## Ghost Tunnel (Experimental)
 
-## Ghost Tunnel
+Ghost Tunnel is an experimental opt-in feature. Its configuration, transports, CLI behavior, and public APIs may change between releases and should not be used for production-critical access.
 
 As a production app, I want one opt-in flag that makes `<route>-<project>-<owner>.ghost.<domain>` a known product entrypoint on top of the deployed Vite app, without running local Caddy or requiring the local `.localghost` file.
 
@@ -141,8 +146,8 @@ When `ghostTunnel` is configured, route and Vite startup logs print the producti
 As a developer, I want to retest setup without deleting my project config.
 
 ```sh
-yarn localghost reset
-yarn localghost setup
+localghost reset
+localghost setup
 ```
 
 `reset` removes only the managed hosts block, generated Caddyfile, and setup state. It leaves `.localghost` in place.
@@ -152,8 +157,8 @@ yarn localghost setup
 As a developer, I want to cleanly remove Localghost from a project when the repo is archived or no longer needs friendly hostnames.
 
 ```sh
-yarn localghost teardown
-yarn localghost teardown --remove-caddyfile
+localghost teardown
+localghost teardown --remove-caddyfile
 ```
 
 `teardown` removes only the Localghost managed `/etc/hosts` block. The generated Caddyfile is kept unless `--remove-caddyfile` is passed.
@@ -163,8 +168,8 @@ yarn localghost teardown --remove-caddyfile
 As a developer or agent, I want to see what Localghost changed without reading system files directly.
 
 ```sh
-yarn localghost status
-yarn localghost status --json
+localghost status
+localghost status --json
 ```
 
 Localghost records setup and teardown in `ops/local/localghost-state.json`. That file is project-local state, not OS temp state.
@@ -174,9 +179,9 @@ Localghost records setup and teardown in `ops/local/localghost-state.json`. That
 As a Codex or agent user, I want commands that are inspectable and scriptable without opening a browser.
 
 ```sh
-yarn localghost print
-yarn localghost doctor
-yarn localghost update
+localghost print
+localghost doctor
+localghost update
 ```
 
 The CLI reference lives in [localghost(1)](./localghost.1.md). Future flows can add MCP helpers and repo templates, but the base package should remain a small, predictable CLI.

package/docs/ghost-tunnel.md

@@ -1,4 +1,7 @@
-# Ghost Tunnel
+# Ghost Tunnel (Experimental)
+
+> [!WARNING]
+> Ghost Tunnel is experimental. Its configuration, transport protocol, CLI behavior, and public APIs may change between releases. Do not rely on it for production-critical access. Review authentication, exposed routes, Redis credentials, and network reachability before sharing a tunnel.
 
 Ghost Tunnel is the production-facing Localghost entrypoint for apps that want a stable wildcard route on top of their existing Vite product:
 

package/docs/github.md

@@ -4,11 +4,11 @@ Use this copy for the GitHub repo About box, topics, and social cards. Keep it s
 
 ## Repository Description
 
-Friendly local hostnames for app repos. Install the dev dependency, run `yarn dev`, and get clean `.localhost` URLs with Caddy and Vite-safe hosts.
+Friendly local hostnames for app repos. Install with npm, pnpm, Yarn, or Bun and get clean `.localhost` URLs with Caddy and Vite-safe hosts.
 
 Shorter alternative:
 
-Friendly local hostnames for app repos. `yarn add -D`, `yarn dev`, ready.
+Friendly local hostnames for app repos. Add the package, run `localghost`, ready.
 
 ## Topics
 
@@ -62,7 +62,7 @@ After creating `hamedb89/localghost`, this sets the public repo metadata:
 
 ```sh
 gh repo edit hamedb89/localghost \
-  --description "Friendly local hostnames for app repos. Install the dev dependency, run yarn dev, and get clean .localhost URLs with Caddy and Vite-safe hosts." \
+  --description "Friendly local hostnames for app repos. Install with npm, pnpm, Yarn, or Bun and get clean .localhost URLs with Caddy and Vite-safe hosts." \
   --homepage "https://hamedb89.github.io/localghost/" \
   --add-topic localhost \
   --add-topic local-development \
@@ -81,7 +81,7 @@ gh repo edit hamedb89/localghost \
 The first visible paragraph should make the entrypoint feel obvious before it gets into configuration:
 
 ```txt
-Localghost is a tiny Node.js CLI for friendly local domains in app repos. Add it as a dev dependency, run `yarn dev`, and use `http://app.localhost/` instead of remembering which localhost port belongs to which process.
+Localghost is a tiny Node.js CLI for friendly local domains in app repos. Add it with your package manager, run `localghost`, and use `http://app.localhost/` instead of remembering which localhost port belongs to which process.
 ```
 
 Then the next docs layer can explain `.localghost`, Caddy, `/etc/hosts`, Vite `allowedHosts`, and configuration options.

package/docs/localghost.1.md

@@ -16,22 +16,24 @@ localghost reset [--project name]
 localghost teardown [--project name] [--remove-caddyfile]
 localghost status [--ready] [--json]
 localghost ps [--json]
+localghost guide [--agent] [--json]
 localghost tunnel [--cwd path] [--config file] [--config-pattern regex] [--ghost-config file] [--target-host host]
+localghost release <patch|minor|major>
 localghost update [--json]
 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 print [--config file] [--config-pattern regex]
 ```
 
-With no subcommand, Localghost detects the package manager from `packageManager` or a lockfile, prefers a non-recursive `dev:raw` script, falls back to `dev`, and runs the result through the normal Caddy lifecycle. `--dry-run` prints the detected command without checking or changing machine setup. Set `command: ["pnpm", "dev:web"]` in `localghost.config.mjs` when inference should be explicit.
+With no subcommand, Localghost detects npm, pnpm, Yarn, or Bun from `packageManager` or a lockfile, prefers a non-recursive `dev:raw` script, falls back to `dev`, and runs the result through the normal Caddy lifecycle. Supported runtime flags such as `--https`, `--clean-caddy`, `--auto-repair`, and `--dynamic-port` are forwarded to that lifecycle. `--dry-run` prints the detected command without checking or changing machine setup. Set `command: ["<package-manager>", "dev:web"]` in `localghost.config.mjs` when inference should be explicit.
 
 For multiple independently started applications, configure `services` in `localghost.config.mjs`. Each service declares a unique name and host plus its project-relative working directory, requested port, and optional command. Bare `localghost` starts one Caddy process and all service commands, passes service-specific `LOCALGHOST_PORT`, `VITE_PORT`, and `LOCALGHOST_SERVICE` variables, and stops the group when any process exits.
 
 ```js
 export default {
   services: [
-    { name: "web", cwd: "apps/web", host: "xyz.localhost", port: 5173, command: ["pnpm", "dev"] },
-    { name: "api", cwd: "apps/api", host: "api.xyz.localhost", port: 8787, command: ["pnpm", "dev"] }
+    { name: "web", cwd: "apps/web", host: "xyz.localhost", port: 5173 },
+    { name: "api", cwd: "apps/api", host: "api.xyz.localhost", port: 8787 }
   ]
 };
 ```
@@ -63,7 +65,7 @@ Options:
 - `--port <number>`: primary app port.
 - `--api-host <host>`: API hostname.
 - `--api-port <number>`: API port.
-- `--package-manager <npm|yarn|pnpm>`: package manager for suggested commands.
+- `--package-manager <npm|pnpm|yarn|bun>`: package manager for suggested commands.
 - `--write-scripts`: add Localghost scripts to `package.json`.
 - `--force`: overwrite an existing config file.
 
@@ -136,7 +138,20 @@ localghost ps
 localghost ps --json
 ```
 
-### tunnel
+### guide
+
+Prints the recommended repository integration and command workflow. Use `--agent` for the coding-agent-oriented guide and `--json` for machine-readable integration hints.
+
+```sh
+localghost guide --agent
+localghost guide --agent --json
+```
+
+Localghost stores remembered project and instance port assignments in `~/.localghost`. Only Localghost-managed processes are represented there; unrelated processes are still checked by the operating system when a port is selected.
+
+### tunnel (experimental)
+
+Ghost Tunnel is experimental. Its configuration, transport protocol, CLI behavior, and public APIs may change between releases; do not rely on it for production-critical access.
 
 Runs the local Ghost Tunnel agent for `ghostTunnel.transport: "tunnel"`. The command reads the Localghost project config, reads exact public hosts from `.ghosttunnel`, sends route heartbeats to the configured Redis REST store, polls for queued requests, and serves them from the matching local port.
 
@@ -154,6 +169,18 @@ Checks npm for a newer Localghost release. Pass `--json` for scripts and agents.
 localghost update
 ```
 
+### release
+
+Dispatches the repository's guarded GitHub Actions release pipeline from `main`. The command requires an installed and authenticated GitHub CLI.
+
+```sh
+localghost release patch
+localghost release minor
+localghost release major
+```
+
+The pipeline synchronizes version metadata, runs package and runtime verification, creates the version commit and tag, publishes npm with provenance, and creates generated GitHub release notes.
+
 ### routes
 
 Prints the local domain layer as `domain -> upstream` routes. HTTP is the default. Pass `--https` or `--ssl` if the browser-facing domain should be shown as HTTPS.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hamedb89/localghost",
-  "version": "0.1.12",
+  "version": "0.1.15",
   "description": "Friendly local hostnames for app repos with .localghost, Caddy, /etc/hosts, and Vite.",
   "type": "module",
   "bin": {